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

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

@@ -0,0 +1,23 @@
+# JOURNAL-lex
+
+## 2026-06-15
+
+### Build
+
+Created `calc/__init__.py` (empty package marker) and `calc/lexer.py` implementing:
+- `Token` dataclass with `kind` (str) and `value` (int | float | None)
+- `LexError(Exception)` raised on invalid characters with offending char and position
+- `tokenize(src: str) -> list[Token]` covering numbers (int/float, leading/trailing dot), operators, parens, whitespace skipping, and error raising
+- `EOF` singleton token appended at end of every token list
+
+Created `calc/test_lexer.py` with 18 unittest cases covering D1–D3 including the three mandatory inputs.
+
+### Verification
+
+All four DoD gates observed passing:
+- D1: integers, floats (3.14, .5, 10.) tokenize correctly with right Python type
+- D2: all six operator/paren kinds correct; `1+2*3` yields expected sequence
+- D3: whitespace skipped; `@` raises LexError with position 2 in message
+- D4: 18 tests, 0 failures
+
+Commit: 70b71caacd1f7334e387ff15b007573201b524b6

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

@@ -0,0 +1,10 @@
+# JOURNAL-parse
+
+## 2026-06-15 — Phase start
+
+Reading plan. Building recursive-descent parser with:
+- Grammar: expr → term ((+|-) term)*; term → factor ((*|/) factor)*; factor → NUMBER | ( expr ) | - factor
+- AST nodes: Num, BinOp, Unary
+- ParseError exception
+
+Plan: implement parser.py, test_parser.py, verify all D1–D6, then certify.

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

@@ -0,0 +1,76 @@
+# STATUS — eval phase
+
+Commit: c6086a4
+
+## Gate verification
+
+### D1 — arithmetic (precedence, parens, unary minus)
+
+Command: `python -m unittest calc.test_evaluator.TestArithmetic -v`
+Expected: 5 tests pass
+
+Observed:
+```
+test_add_mul_precedence (calc.test_evaluator.TestArithmetic) ... ok    # 2+3*4=14
+test_left_associative_subtraction (calc.test_evaluator.TestArithmetic) ... ok    # 8-3-2=3
+test_parens (calc.test_evaluator.TestArithmetic) ... ok    # (2+3)*4=20
+test_unary_minus_leading (calc.test_evaluator.TestArithmetic) ... ok    # -2+5=3
+test_unary_minus_rhs (calc.test_evaluator.TestArithmetic) ... ok    # 2*-3=-6
+PASS
+```
+
+### D2 — division (true division + EvalError on zero)
+
+Command: `python -m unittest calc.test_evaluator.TestDivision -v`
+Expected: 4 tests pass, ZeroDivisionError never escapes
+
+Observed:
+```
+test_divide_by_zero_expression_raises_eval_error ... ok
+test_divide_by_zero_raises_eval_error ... ok
+test_no_bare_zero_division_error ... ok
+test_true_division ... ok   # 7/2=3.5
+PASS
+```
+
+### D3 — result type (whole → int, fractional → float)
+
+Command: `python -m unittest calc.test_evaluator.TestResultType -v`
+Expected: 4 tests pass
+
+Observed:
+```
+test_fractional_division_returns_float ... ok   # 7/2 is float
+test_integer_add_returns_int ... ok
+test_integer_mul_returns_int ... ok
+test_whole_division_returns_int ... ok   # 4/2 is int
+PASS
+```
+
+### D4 — CLI
+
+Commands and observed outputs:
+
+| Command | Expected | Observed | Exit |
+|---|---|---|---|
+| `python calc.py "2+3*4"` | `14` | `14` | 0 |
+| `python calc.py "(2+3)*4"` | `20` | `20` | 0 |
+| `python calc.py "7/2"` | `3.5` | `3.5` | 0 |
+| `python calc.py "4/2"` | `2` | `2` | 0 |
+| `python calc.py "1/0"` | error→stderr, exit≠0 | `Error: Division by zero` (stderr), stdout empty | 1 |
+| `python calc.py "1 +"` | error→stderr, exit≠0 | `Error: Unexpected end of input` (stderr) | 1 |
+
+### D5 — whole suite + no regression
+
+Command: `python -m unittest -q`
+Expected: all tests pass, 0 failures
+
+Observed:
+```
+Ran 59 tests in 0.231s
+OK
+```
+
+Prior lex + parse tests: included in the 59, all pass.
+
+## DONE

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

@@ -0,0 +1,112 @@
+# STATUS-lex
+
+Commit: 70b71caacd1f7334e387ff15b007573201b524b6
+
+## Gate Results
+
+### D1 — numbers
+
+**Check:** `tokenize("42")` → `[NUMBER(42), EOF]`; also `.5`, `3.14`, `10.` tokenize to float NUMBER.
+
+**Command:**
+```bash
+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)]` ✓
+
+Additional verified: `.5` → `NUMBER(0.5, float)`, `10.` → `NUMBER(10.0, float)`, `3.14` → `NUMBER(3.14, float)`
+
+**Result: PASS**
+
+---
+
+### D2 — operators & parens
+
+**Check:** `tokenize("1+2*3")` → `NUMBER PLUS NUMBER STAR NUMBER EOF`
+
+**Command:**
+```bash
+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:** `['NUMBER', 'PLUS', 'NUMBER', 'STAR', 'NUMBER', 'EOF']` ✓
+
+All operator kinds verified: PLUS, MINUS, STAR, SLASH, LPAREN, RPAREN.
+
+**Result: PASS**
+
+---
+
+### D3 — whitespace & errors
+
+**Check 1 (whitespace):** `"  12  +  3 "` → `NUMBER PLUS NUMBER EOF`
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('  12  +  3 ')])"
+```
+
+**Expected:** `[('NUMBER', 12), ('PLUS', '+'), ('NUMBER', 3), ('EOF', None)]`
+
+**Observed:** `[('NUMBER', 12), ('PLUS', '+'), ('NUMBER', 3), ('EOF', None)]` ✓
+
+**Check 2 (LexError):** `"1 @ 2"` raises `LexError` with `@` and position in message.
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"
+```
+
+**Expected:** `LexError: Invalid character '@' at position 2`
+
+**Observed:**
+```
+calc.lexer.LexError: Invalid character '@' at position 2
+```
+✓
+
+**Result: PASS**
+
+---
+
+### D4 — tests green
+
+**Command:**
+```bash
+python -m unittest -q
+```
+
+**Expected:** 0 failures
+
+**Observed:**
+```
+----------------------------------------------------------------------
+Ran 18 tests in 0.000s
+
+OK
+```
+✓
+
+**Result: PASS**
+
+---
+
+### Plan verification commands
+
+```bash
+python -m unittest -q
+# Ran 18 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: Invalid character '@' at position 2
+```
+
+## DONE

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

@@ -0,0 +1,175 @@
+# STATUS-parse
+
+Phase: parse
+
+## AST Shape
+
+Nodes are dataclasses from `calc.parser`:
+
+- `Num(value)` — leaf; value is int or float
+  - repr: `Num(value=42)`
+- `BinOp(op, left, right)` — binary operation; op in ('+', '-', '*', '/')
+  - repr: `BinOp(op='+', left=Num(value=1), right=BinOp(op='*', left=Num(value=2), right=Num(value=3)))`
+- `Unary(op, operand)` — unary minus; op is '-'
+  - repr: `Unary(op='-', operand=Num(value=5))`
+
+## Gate Results
+
+### D1 — precedence
+
+**Check:** `1+2*3` parses as `1+(2*3)`, not `(1+2)*3`
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('1+2*3')))"
+```
+
+**Expected:** `BinOp(op='+', left=Num(value=1), right=BinOp(op='*', left=Num(value=2), right=Num(value=3)))`
+
+**Observed:** `BinOp(op='+', left=Num(value=1), right=BinOp(op='*', left=Num(value=2), right=Num(value=3)))` ✓
+
+**Result: PASS**
+
+---
+
+### D2 — left associativity
+
+**Check:** `8-3-2` parses as `(8-3)-2`; `8/4/2` as `(8/4)/2`
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('8-3-2'))); print(parse(tokenize('8/4/2')))"
+```
+
+**Expected:**
+- `BinOp(op='-', left=BinOp(op='-', left=Num(value=8), right=Num(value=3)), right=Num(value=2))`
+- `BinOp(op='/', left=BinOp(op='/', left=Num(value=8), right=Num(value=4)), right=Num(value=2))`
+
+**Observed:**
+```
+BinOp(op='-', left=BinOp(op='-', left=Num(value=8), right=Num(value=3)), right=Num(value=2))
+BinOp(op='/', left=BinOp(op='/', left=Num(value=8), right=Num(value=4)), right=Num(value=2))
+```
+✓
+
+**Result: PASS**
+
+---
+
+### D3 — parentheses
+
+**Check:** `(1+2)*3` parses with `+` under `*`
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('(1+2)*3')))"
+```
+
+**Expected:** `BinOp(op='*', left=BinOp(op='+', left=Num(value=1), right=Num(value=2)), right=Num(value=3))`
+
+**Observed:** `BinOp(op='*', left=BinOp(op='+', left=Num(value=1), right=Num(value=2)), right=Num(value=3))` ✓
+
+**Result: PASS**
+
+---
+
+### D4 — unary minus
+
+**Check:** `-5`, `-(1+2)`, `3 * -2` all parse correctly
+
+**Command:**
+```bash
+python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('-5'))); print(parse(tokenize('-(1+2)'))); print(parse(tokenize('3 * -2')))"
+```
+
+**Expected:**
+- `Unary(op='-', operand=Num(value=5))`
+- `Unary(op='-', operand=BinOp(op='+', left=Num(value=1), right=Num(value=2)))`
+- `BinOp(op='*', left=Num(value=3), right=Unary(op='-', operand=Num(value=2)))`
+
+**Observed:**
+```
+Unary(op='-', operand=Num(value=5))
+Unary(op='-', operand=BinOp(op='+', left=Num(value=1), right=Num(value=2)))
+BinOp(op='*', left=Num(value=3), right=Unary(op='-', operand=Num(value=2)))
+```
+✓
+
+**Result: PASS**
+
+---
+
+### D5 — errors
+
+**Check:** `"1 +"`, `"(1"`, `"1 2"`, `")("`, `""` each raise `ParseError`
+
+**Command:**
+```bash
+python -c "
+from calc.lexer import tokenize
+from calc.parser import parse, ParseError
+
+cases = ['1 +', '(1', '1 2', ')(', '']
+for src in cases:
+    try:
+        parse(tokenize(src))
+        print(f'FAIL: {src!r} did not raise ParseError')
+    except ParseError as e:
+        print(f'PASS: {src!r} -> ParseError: {e}')
+    except Exception as e:
+        print(f'FAIL: {src!r} raised wrong exception {type(e).__name__}: {e}')
+"
+```
+
+**Expected:** All 5 cases print PASS
+
+**Observed:**
+```
+PASS: '1 +' -> ParseError: Unexpected end of input
+PASS: '(1' -> ParseError: Expected RPAREN but got 'EOF'
+PASS: '1 2' -> ParseError: Unexpected token NUMBER(2)
+PASS: ')(' -> ParseError: Unexpected token RPAREN(')')
+PASS: '' -> ParseError: Unexpected end of input
+```
+✓
+
+**Result: PASS**
+
+---
+
+### D6 — tests green
+
+**Command:**
+```bash
+python -m unittest -q
+```
+
+**Expected:** 0 failures
+
+**Observed:**
+```
+----------------------------------------------------------------------
+Ran 40 tests in 0.001s
+
+OK
+```
+✓ (40 = 18 from lex + 22 from parser)
+
+**Result: PASS**
+
+---
+
+## Cold-verify commands (for independent re-run)
+
+```bash
+python -m unittest -q
+# Expected: Ran 40 tests ... OK
+
+python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('1+2*3')))"
+# Expected: BinOp(op='+', left=Num(value=1), right=BinOp(op='*', left=Num(value=2), right=Num(value=3)))
+
+python -c "from calc.lexer import tokenize; from calc.parser import parse; parse(tokenize('1 +'))"
+# Expected: ParseError: Unexpected end of input
+```
+
+## DONE