artifacts: add calculators/ — the 30 built calculators (5/variant) + machine-docs + git logs

calculators/builder-solo/run-04/machine-docs/JOURNAL-eval.md

@@ -0,0 +1,21 @@
+# JOURNAL — eval phase
+
+## Build log
+
+1. Read `calc/parser.py` to understand AST node types: `Num`, `BinOp`, `Unary`.
+2. Created `calc/evaluator.py`:
+   - `EvalError` exception for API-safe error surface.
+   - `evaluate(node)` walks AST recursively.
+   - Division uses true division (`/`); div-by-zero raises `EvalError`.
+   - Whole-valued float results are returned as `int` (D3 rule).
+3. Created `calc/test_evaluator.py`:
+   - `TestArithmetic` covers all D1 expressions.
+   - `TestDivision` verifies true division, `EvalError` on zero, and that `ZeroDivisionError` does not escape.
+   - `TestResultType` checks int/float return types.
+   - `TestCLI` uses subprocess to verify D4 (exit codes, stderr output).
+4. Created top-level `calc.py` CLI:
+   - Accepts one argument, runs the full pipeline.
+   - Catches `LexError`, `ParseError`, `EvalError` and prints to stderr with exit 1.
+   - No traceback on error.
+5. Ran `python -m unittest -q` → 49 tests, 0 failures.
+6. Ran all 8 CLI checks from the plan — all match expected output.

calculators/builder-solo/run-04/machine-docs/JOURNAL-lex.md

@@ -0,0 +1,18 @@
+# JOURNAL-lex
+
+## 2026-06-15
+
+**Built:** `calc/__init__.py`, `calc/lexer.py`, `calc/test_lexer.py`, `.gitignore`
+
+**Design decisions:**
+- `Token` is a `@dataclass` with `kind: str` and `value: Union[int, float, str, None]`
+- Operators/parens carry their char as value; EOF carries `None`
+- Number parsing: scans contiguous digits/dots; if `.` present → `float()`, else `int()`
+- `LexError` extends `Exception`; message includes repr of bad char and its index
+
+**Verification (all 3 plan commands passed):**
+1. `python -m unittest -q` → 15 tests, 0 failures
+2. `tokenize('3.5*(1-2)')` → correct 8-token list
+3. `tokenize('1 @ 2')` → raises `LexError: unexpected character '@' at position 2`
+
+**Commit:** c37b70f — pushed to origin/main

calculators/builder-solo/run-04/machine-docs/JOURNAL-parse.md

@@ -0,0 +1,16 @@
+# JOURNAL-parse
+
+## Session 1
+
+Built `calc/parser.py` — recursive-descent parser with grammar:
+- `expr → term (('+' | '-') term)*`
+- `term → unary (('*' | '/') unary)*`
+- `unary → '-' unary | primary`
+- `primary → NUMBER | '(' expr ')'`
+
+Left associativity achieved via iterative loops (not recursion) in `expr` and `term`.
+Unary minus handled in its own `unary` rule, which recurses right.
+
+Built `calc/test_parser.py` with 19 tests (35 total including lex tests) covering D1–D5.
+
+All DoD gates passed on first run.

calculators/builder-solo/run-04/machine-docs/STATUS-eval.md

@@ -0,0 +1,62 @@
+# STATUS — eval phase
+
+## Gate verification
+
+### D1 — arithmetic
+
+| Expression | Expected | Command | Observed |
+|------------|----------|---------|----------|
+| `2+3*4` | 14 | `python calc.py "2+3*4"` | `14` |
+| `(2+3)*4` | 20 | `python calc.py "(2+3)*4"` | `20` |
+| `8-3-2` | 3 | `python calc.py "8-3-2"` | `3` |
+| `-2+5` | 3 | `python calc.py "-2+5"` | `3` |
+| `2*-3` | -6 | `python calc.py "2*-3"` | `-6` |
+
+**Result: PASS**
+
+### D2 — division / EvalError
+
+| Check | Command | Expected | Observed |
+|-------|---------|----------|----------|
+| True division | `python calc.py "7/2"` | `3.5` | `3.5` |
+| Div-by-zero stderr + exit 1 | `python calc.py "1/0"` | error to stderr, exit 1 | `error: division by zero`, exit 1 |
+| EvalError (not ZeroDivisionError) | unittest | EvalError raised | PASS (test_no_bare_zero_division_error) |
+
+**Result: PASS**
+
+### D3 — result type
+
+| Check | Command | Expected | Observed |
+|-------|---------|----------|----------|
+| Whole result as int | `python calc.py "4/2"` | `2` (no `.0`) | `2` |
+| Non-whole as float | `python calc.py "7/2"` | `3.5` | `3.5` |
+
+**Result: PASS**
+
+### D4 — CLI
+
+| Check | Command | Expected | Observed |
+|-------|---------|----------|----------|
+| Valid expression → stdout + exit 0 | `python calc.py "2+3*4"` | `14`, exit 0 | `14`, exit 0 |
+| Invalid expression → stderr + exit non-zero | `python calc.py "1 +"` | error to stderr, exit 1 | `error: unexpected end of input`, exit 1 |
+| Div-by-zero → stderr + exit non-zero | `python calc.py "1/0"` | error to stderr, exit 1 | `error: division by zero`, exit 1 |
+
+**Result: PASS**
+
+### D5 — tests green + no regression
+
+Command: `python -m unittest -q`
+
+Expected: 0 failures, covers D1–D3 + prior suite (lex + parse)
+
+Observed:
+```
+----------------------------------------------------------------------
+Ran 49 tests in 0.105s
+
+OK
+```
+
+**Result: PASS**
+
+## DONE

calculators/builder-solo/run-04/machine-docs/STATUS-lex.md

@@ -0,0 +1,64 @@
+# STATUS-lex
+
+Phase: `lex`
+Commit: c37b70f
+
+## Gate Results
+
+### D1 — numbers
+**What:** Integers and floats tokenize to NUMBER tokens with correct Python values (int or float).
+**Command:** `python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('42')])"` 
+**Expected:** `[('NUMBER', 42), ('EOF', None)]`
+**Observed:** `[('NUMBER', 42), ('EOF', None)]`
+**Result:** PASS
+
+Float test: `tokenize("3.14")` → `[('NUMBER', 3.14), ('EOF', None)]` ✓
+Leading dot: `tokenize(".5")` → `[('NUMBER', 0.5), ('EOF', None)]` ✓
+Trailing dot: `tokenize("10.")` → `[('NUMBER', 10.0), ('EOF', None)]` ✓
+
+### D2 — operators & parens
+**What:** `+ - * / ( )` tokenize to correct kinds; `"1+2*3"` yields NUMBER PLUS NUMBER STAR NUMBER EOF.
+**Command:** `python -c "from calc.lexer import tokenize; print([t.kind for t in tokenize('1+2*3')])"`
+**Expected:** `['NUMBER', 'PLUS', 'NUMBER', 'STAR', 'NUMBER', 'EOF']`
+**Observed:** Confirmed via test suite (15/15 tests pass)
+**Result:** PASS
+
+### D3 — whitespace & errors
+**What:** Spaces/tabs skipped; invalid chars raise LexError with char and position.
+**Command (whitespace):** `python -c "from calc.lexer import tokenize; print([t.kind for t in tokenize('  12  +  3 ')])"`
+**Observed:** `['NUMBER', 'PLUS', 'NUMBER', 'EOF']` ✓
+
+**Command (error):** `python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"`
+**Expected:** raises `LexError` with `@` and position in message
+**Observed:**
+```
+calc.lexer.LexError: unexpected character '@' at position 2
+```
+**Result:** PASS
+
+### D4 — tests green
+**Command:** `python -m unittest -q`
+**Expected:** 0 failures
+**Observed:**
+```
+----------------------------------------------------------------------
+Ran 15 tests in 0.000s
+
+OK
+```
+**Result:** PASS
+
+### Plan verification commands (from plan's "Verify" section)
+
+```
+python -m unittest -q
+→ Ran 15 tests in 0.000s / OK
+
+python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('3.5*(1-2)')])"
+→ [('NUMBER', 3.5), ('STAR', '*'), ('LPAREN', '('), ('NUMBER', 1), ('MINUS', '-'), ('NUMBER', 2), ('RPAREN', ')'), ('EOF', None)]
+
+python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"
+→ calc.lexer.LexError: unexpected character '@' at position 2
+```
+
+## DONE

calculators/builder-solo/run-04/machine-docs/STATUS-parse.md

@@ -0,0 +1,56 @@
+# STATUS-parse
+
+Phase: `parse`
+Files: `calc/parser.py`, `calc/test_parser.py`
+
+## AST Shape
+
+```
+Num(value)              — leaf; value is int or float
+BinOp(op, left, right)  — op ∈ {'+', '-', '*', '/'}; left and right are Nodes
+Unary(op, operand)      — op is '-'; operand is a Node
+```
+
+All nodes are `@dataclass` with custom `__repr__`.  
+`parse(tokens) -> Node` accepts the list returned by `calc.lexer.tokenize`.  
+`ParseError(Exception)` is raised for all malformed input.
+
+## Gate Verification
+
+### D1 — Precedence
+**Command:** `python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('1+2*3')))"`  
+**Expected:** `BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))`  
+**Observed:** `BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))` ✓ **PASS**
+
+### D2 — Left Associativity
+**Command:** parse `8-3-2` and `8/4/2`  
+**Expected:** `BinOp('-', BinOp('-', Num(8), Num(3)), Num(2))` and `BinOp('/', BinOp('/', Num(8), Num(4)), Num(2))`  
+**Observed:** Both matched exactly ✓ **PASS**
+
+### D3 — Parentheses
+**Command:** parse `(1+2)*3`  
+**Expected:** `BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))`  
+**Observed:** `BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))` ✓ **PASS**
+
+### D4 — Unary Minus
+**Commands:** parse `-5`, `-(1+2)`, `3 * -2`  
+**Expected:** `Unary('-', Num(5))`, `Unary('-', BinOp('+', Num(1), Num(2)))`, `BinOp('*', Num(3), Unary('-', Num(2)))`  
+**Observed:** All three matched exactly ✓ **PASS**
+
+### D5 — Errors
+**Inputs tested:** `"1 +"`, `"(1"`, `"1 2"`, `")("`, `""`  
+**Expected:** Each raises `ParseError`  
+**Observed:**
+- `"1 +"` → `ParseError: unexpected end of input` ✓
+- `"(1"` → `ParseError: unclosed '(' — expected ')'` ✓
+- `"1 2"` → `ParseError: unexpected token Token(kind='NUMBER', value=2) after expression` ✓
+- `")("` → `ParseError: unexpected token 'RPAREN' (')')` ✓
+- `""` → `ParseError: unexpected end of input` ✓
+**PASS**
+
+### D6 — Tests Green
+**Command:** `python -m unittest -q`  
+**Expected:** 0 failures  
+**Observed:** `Ran 35 tests in 0.001s — OK` ✓ **PASS**
+
+## DONE