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.