level: raise InputError on user CBS formula division by zero

Wrap safe_eval_formula in _user_fn so degenerate inputs surface the
formula text and cardinal map instead of a raw ZeroDivisionError.
Also add the missing return annotations on _resolve_formula/_user_fn.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: alongd

arc/level/protocol.py

@@ -41,7 +41,7 @@
 
 import copy
 from abc import ABC, abstractmethod
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from typing import Any
 
 from arc.exceptions import InputError
@@ -295,7 +295,7 @@ def __init__(
     _USER_FORMULA_MAX_LEVELS = 3
 
     @staticmethod
-    def _resolve_formula(formula: str, n_levels: int):
+    def _resolve_formula(formula: str, n_levels: int) -> Callable[[dict[int, float]], float]:
         """Validate ``formula`` against the built-in registry and (if user-supplied)
         the safe-eval whitelist; return a callable taking ``{cardinal: energy}``.
 
@@ -324,13 +324,19 @@ def _resolve_formula(formula: str, n_levels: int):
         allowed.update({var for var in ("X", "Y", "Z")[:n_levels]})
         validate_formula(formula, allowed)
 
-        def _user_fn(energies):
-            env = {}
+        def _user_fn(energies: dict[int, float]) -> float:
+            env: dict[str, float] = {}
             for idx, (X, E) in enumerate(sorted(energies.items())):
                 var = ("X", "Y", "Z")[idx]
                 env[var] = X
                 env[f"E_{var}"] = E
-            return safe_eval_formula(formula, env)
+            try:
+                return safe_eval_formula(formula, env)
+            except ZeroDivisionError as exc:
+                raise InputError(
+                    f"User CBS formula {formula!r} raised division by zero "
+                    f"for inputs {energies}."
+                ) from exc
 
         return _user_fn
 

arc/level/protocol_test.py

@@ -128,6 +128,18 @@ def test_evaluate_user_formula(self):
         expected = (27 * -0.30 - 64 * -0.31) / (27 - 64)
         self.assertAlmostEqual(result, expected, places=12)
 
+    def test_evaluate_user_formula_zero_division_reports_formula_and_inputs(self):
+        term = CBSExtrapolationTerm(
+            label="cbs_user",
+            formula="E_X / (E_Y - E_X)",
+            levels=[self.tz, self.qz],
+        )
+        with self.assertRaises(InputError) as cm:
+            term.evaluate({"cbs_user__card_3": -0.30, "cbs_user__card_4": -0.30})
+        message = str(cm.exception)
+        self.assertIn("E_X / (E_Y - E_X)", message)
+        self.assertIn("{3: -0.3, 4: -0.3}", message)
+
     def test_three_point_martin(self):
         term = CBSExtrapolationTerm(
             label="cbs_m", formula="martin_3pt", levels=[self.tz, self.qz, self.fz]