Editorial revision

Author: ehsanmok

book/src/01_calculator/ast.md

@@ -56,10 +56,10 @@ This handles `-1` (minus applied to 1) or `-(2 + 3)` (minus applied to a whole e
 **Binary expressions** - An operator between two things:
 
 ```
-BinaryExpr = { Term ~ (Operator ~ Term)* }
+BinaryExpr = { (UnaryExpr | Term) ~ (Operator ~ Term)+ }
 ```
 
-This handles `1 + 2` (plus between 1 and 2) or `1 + 2 + 3` (chained additions).
+This handles `1 + 2` (plus between 1 and 2) or `1 + 2 + 3` (chained additions). The `+` (one or more) requires at least one operator, which keeps a lone `Term` from matching as a binary expression.
 
 Here's a complex example: `"-1 + (2 + 3)"` forms this tree:
 
@@ -117,7 +117,7 @@ The core insight is **recursion**. To evaluate `1 + 2`:
 2. Evaluate the right side (`2`) → get `2`
 3. Apply the operator (`+`) → get `3`
 
-If the left side were `(3 + 4)` instead of `1`, we'd recursively evaluate that first. This is why trees are so powerful - the structure tells us the order of operations.
+If the left side were `(3 + 4)` instead of `1`, we'd recursively evaluate that first. This is what the tree buys us: the structure itself encodes the order of operations.
 
 Here's the evaluation function:
 
@@ -161,7 +161,7 @@ Run tests locally with:
 cargo test interpreter --tests
 ```
 
-## Why This Pattern Matters
+## The Tree-Walking Pattern
 
 The pattern we just learned - parse to AST, recursively evaluate - is the foundation of *every* interpreter. Python, Ruby, JavaScript interpreters all do this (with more node types, of course).
 
@@ -170,7 +170,7 @@ In the next sections, we'll see two other ways to execute the same AST:
 - **JIT compilation** - Convert the AST to machine code, then run it
 - **Bytecode VM** - Convert to simpler instructions, then interpret those
 
-Same AST, three different backends. That's the power of separating parsing from execution.
+Same AST, three different backends. That is what separating parsing from execution gives us.
 
 <div class="checkpoint">
 

book/src/01_calculator/ast_traversal.md

@@ -57,20 +57,20 @@ Let's trace through what happens when we JIT `1 + 2`:
 
 2. **Setup LLVM** - Create context, module, builder
 
-3. **Create wrapper function** - We need a function to call, so we create `__jit` with signature `() -> i64`
+3. **Create wrapper function** - We need a function to call, so we create `jit` with signature `() -> i32`
 
 4. **Compile AST** - `recursive_builder` walks the tree:
-   * Compile `Int(1)` → creates i64 constant `1`
-   * Compile `Int(2)` → creates i64 constant `2`
-   * Compile `Add` → creates `add i64 1, 2` instruction, returns the result
+   * Compile `Int(1)` → creates i32 constant `1`
+   * Compile `Int(2)` → creates i32 constant `2`
+   * Compile `Add` → creates `add i32 1, 2` instruction, returns the result
 
 5. **Return result** - `build_return` emits a `ret` instruction with our computed value
 
 6. **JIT compile** - LLVM turns our IR into native machine code
 
 7. **Execute** - Call the function, get `3`
 
-### Why This Matters
+### Scaling to Any Expression
 
 The recursive builder pattern scales to any expression, no matter how complex:
 

book/src/01_calculator/basic_llvm.md

@@ -83,7 +83,7 @@ Walking through this:
 
 ### Step 3: Build the Function Body
 
-Now the fun part - generating the actual addition:
+Now we generate the actual addition:
 
 ```rust,ignore
 {{#include ../../../calculator/examples/llvm/src/main.rs:third}}
@@ -106,7 +106,7 @@ Time to turn our IR into machine code and run it:
 {{#include ../../../calculator/examples/llvm/src/main.rs:fourth}}
 ```
 
-This is where it gets real:
+Here the IR becomes executable code:
 
 - **`module.create_jit_execution_engine(OptimizationLevel::None)`** - Creates a JIT compiler. LLVM takes our IR and compiles it to native x86/ARM code *right now*, in memory.
 - **`execution_engine.get_function::<unsafe extern "C" fn(i32, i32) -> i32>("add")`** - Look up our compiled function. The type signature tells Rust how to call it.

book/src/01_calculator/debugging.md

@@ -127,6 +127,29 @@ The verifier catches:
 
 Always verify before JIT execution!
 
+## How Errors Surface Today
+
+Our languages report errors as values, not exceptions. Each stage hands back a `Result`: the calculator uses `anyhow::Result<T>`, while Firstlang, Secondlang, and Thirdlang return `Result<T, String>`. There are three kinds you will meet:
+
+- **Parse errors** come from pest and already carry a line and column:
+
+```text
+Parse error:  --> 8:9
+  |
+8 |     def classify(self) -> int {
+  |         ^---
+  |
+  = expected Identifier
+```
+
+- **Type errors** come from the type checker as plain strings, for example `Type mismatch: expected int, got bool`.
+
+- **Setup and I/O errors**, such as pointing the CLI at a file that does not exist.
+
+The CLIs for Firstlang, Secondlang, and Thirdlang print these with `eprintln!` and exit non-zero. The calculator is the exception: its entry point still `unwrap()`s the file read and the parse result, so a missing file or a syntax error there ends in a panic rather than a tidy message.
+
+Two limits are worth naming. First, type-error strings have no source location, so they tell you *what* is wrong but not *where*. Second, the first error stops the pipeline; you fix one, rerun, and find the next. Real compilers attach a span to every diagnostic and recover to report several at once. We sketch how to get there in [What's Next](../whats_next.md#path-4-better-error-handling).
+
 ## The Debugging Mindset
 
 > Think like a detective. You have a crime (wrong output). You need to find where in the pipeline the crime occurred. Interrogate each stage until you find the culprit.

book/src/01_calculator/grammar_lexer_parser.md

@@ -31,7 +31,7 @@ Don't let this overwhelm you - let's break it down line by line:
 
 **`Program = _{ SOI ~ Expr ~ EOF }`** - A program is an expression, surrounded by "start of input" (`SOI`) and "end of file" (`EOF`). The `_{ }` means we don't create a node for `Program` itself - it's just a wrapper.
 
-**`Expr = { UnaryExpr | BinaryExpr | Term }`** - An expression is either unary (`-1`), binary (`1 + 2`), or a simple term (just a number). The `|` means "or" - try each alternative in order.
+**`Expr = { BinaryExpr | UnaryExpr | Term }`** - An expression is either binary (`1 + 2`), unary (`-1`), or a simple term (just a number). The `|` means "or", and PEG tries each alternative in order, so `BinaryExpr` is attempted first.
 
 **`Term = { Int | "(" ~ Expr ~ ")" }`** - A term is either a number or a parenthesized expression. This is how we handle `(1 + 2) * 3` - the parenthesized part becomes a single term.
 
@@ -67,9 +67,9 @@ CalcParser::parse(Rule::Program, source)
 
 This returns a tree of "pairs" - pest's way of representing matched rules. In the [next section](./ast.md), we'll convert these pairs into our own AST structure, which is easier to work with.
 
-## Why This Matters
+## Why Not Just Use Regexes?
 
-You might wonder: why not just use regular expressions? For a simple calculator, you probably could. But as languages get more complex (nested expressions, functions, classes), grammars scale and regexes don't.
+For a simple calculator, you probably could use regular expressions. But as languages get more complex (nested expressions, functions, classes), grammars scale and regexes don't.
 
 The grammar is also your language's specification. When someone asks "is `--1` valid?", you look at the grammar. When you add a new feature, you extend the grammar. It's the single source of truth for what your language accepts.
 

book/src/01_calculator/vm.md

@@ -12,7 +12,7 @@ This is how Python, Java, Ruby, and many other languages work. You compile sourc
 
 ### What Is Bytecode?
 
-Think of bytecode as a *simplified assembly language* designed for our VM. Real assembly has hundreds of instructions. Our bytecode has just four:
+Think of bytecode as a *simplified assembly language* designed for our VM. Real assembly has hundreds of instructions. These four carry the arithmetic:
 
 | Opcode | What it does |
 |--------|--------------|
@@ -21,7 +21,7 @@ Think of bytecode as a *simplified assembly language* designed for our VM. Real
 | `OpSub` | Pop two values, push their difference |
 | `OpPop` | Pop and discard the top value |
 
-That's it! With just these four operations, we can evaluate any arithmetic expression.
+The full enum also has `OpPlus` and `OpMinus` for unary expressions, but these four are enough to evaluate any binary arithmetic expression.
 
 ## Step 1: Define Opcodes
 

book/src/02_firstlang/control_flow.md

@@ -85,7 +85,7 @@ max(10, 20)  # 20
 max(20, 10)  # 20
 ```
 
-The condition `a > b` determines which value to return. Simple, but powerful.
+The condition `a > b` determines which value to return.
 
 ## Loops: While
 
@@ -191,7 +191,7 @@ Same result, different approach. Loops and recursion are often interchangeable.
 
 ## Control Flow in Functions
 
-The real power comes from combining everything. Here's a more complex example:
+Combining these constructs is where real programs take shape. Here's a more complex example:
 
 ```
 def countdown(n) {
@@ -243,7 +243,7 @@ find_first_even(5)  # 2
 
 When `i = 2`, the condition `i % 2 == 0` is true, and we return immediately. The loop doesn't continue to `i = 3, 4, 5`. This "early return" pattern is common and efficient.
 
-## What Happens Under the Hood
+## Control Flow as Branching
 
 Both `if` and `while` are about *changing the flow of execution*. Without them, we execute line by line. With them, we can:
 

book/src/02_firstlang/fibonacci.md

@@ -47,7 +47,7 @@ This is simple, but let's trace through what happens when we call `fib(4)`:
 
 Each call creates a new stack frame in our interpreter, and when the function returns, we pop the frame and continue with the result.
 
-## Why This Works
+## How Our Interpreter Handles This
 
 Our interpreter properly handles recursion because:
 

book/src/02_firstlang/functions.md

@@ -150,7 +150,7 @@ When we call `outer()`:
 
 The stack grows when functions are called and shrinks when they return. This is why we call it a *stack* - last in, first out.
 
-## Why Frames Matter
+## One Frame Per Call
 
 Consider this code:
 
@@ -220,4 +220,4 @@ The call stack during `quadruple(5)`:
 
 Notice how `x` has different values in different frames, even though they're all named `x`.
 
-Next, we'll add [control flow](./control_flow.md) to make our functions more powerful - the ability to make decisions and repeat actions.
+Next, we'll add [control flow](./control_flow.md): the ability to make decisions and repeat actions.

book/src/02_firstlang/intro.md

@@ -12,12 +12,12 @@ The Calculator grammar was minimal:
 
 ```text
 Program = _{ SOI ~ Expr ~ EOF }
-Expr = { UnaryExpr | BinaryExpr | Term }
-Term = _{Int | "(" ~ Expr ~ ")" }
+Expr = { BinaryExpr | UnaryExpr | Term }
+Term = { Int | "(" ~ Expr ~ ")" }
 UnaryExpr = { Operator ~ Term }
-BinaryExpr = { Term ~ (Operator ~ Term)+ }
+BinaryExpr = { (UnaryExpr | Term) ~ (Operator ~ Term)+ }
 Operator = { "+" | "-" }
-Int = @{ Operator? ~ ASCII_DIGIT+ }
+Int = @{ ASCII_DIGIT+ }
 ```
 
 Firstlang adds *statements*, *identifiers*, *functions*, and *control flow*: