S4.6 — Binding error hierarchy

Intent

Python callers get a bare Exception with a message new_err(e.to_string()) — 25 sites across the four planners) and JS callers get thrown strings (map_err(|e| e.to_string()) — 30 sites. Give both bindings typed errors, and re-raise users' own exceptions unwrapped. Absorbs the backlog item "Robust binding errors" and resolves the TODO callouts at docs/src/python_api.md:129 and docs/src/js_api.md:179.

Decisions (ADR-0003; grilling Q16/Q18)

• Python: base OxmplError(Exception) with subclasses PlanningTimeout, NoSolutionFound, InvalidStartState, SamplingError, PlannerUninitialised, ConfigurationError. Map each PlanningError / StateSamplingError variant to one class; non-exhaustive enums need a catch-all → OxmplError.
• JS: class OxmplError extends Error with a string kind field ("Timeout", "NoSolutionFound", "InvalidStartState", "Sampling", "PlannerUninitialised", "Configuration").
• PlanningError::User / StateSamplingError::User (S4.2) carry the original PyErr / JsValue; the binding re-raises it unchanged (traceback intact; KeyboardInterrupt stays KeyboardInterrupt), as OMPL's Python bindings do.
• ConfigurationError is raised by S4.5's "already in use" checks and S4.7's "missing check_motion" check.

Acceptance criteria

• Python exception classes defined (pyo3 create_exception!), exported from the module, documented
• JS OxmplError exported with kind; TypeScript declaration
• Every planner error path in both bindings maps to the typed error (no bare PyException, no thrown strings left: rg "PyException::new_err|e.to_string\(\)" oxmpl-py/src oxmpl-js/src reviewed)
• User errors re-raised unchanged: test that a checker raising ValueError surfaces as that same ValueError with its traceback, and a goal raising KeyboardInterrupt surfaces as KeyboardInterrupt
• Regression test reproducing the 0.7.0 probe: a checker with a typo raises the user's AttributeError immediately — no path returned, no stderr spam, well under the timeout
• JS equivalent: a checker that throws makes solve throw the same value
• Docs TODO callouts replaced with the real error reference
• just test-all green; commit marked breaking

Tasks

• oxmpl-py/src/ error module + mapping helper; replace the 25 PyException::new_err sites (geometric/rrt.rs 6, rrt_connect.rs 6, rrt_star.rs 6, prm.rs 7)
• oxmpl-js/src/ error class + mapping helper; replace the 30 e.to_string() sites (geometric/rrt.rs 6, rrt_connect.rs 6, rrt_star.rs 6, prm.rs 12)
• Downcast UserError back to PyErr / the JS wrapper type to re-raise
• Update oxmpl-py/tests/test_sampling_errors.py, oxmpl-js/tests/test_sampling_errors.test.js to assert types
• Docs: python_api.md, js_api.md error sections

Source

Agreed in the senior-engineer grilling 2026-10-08 (decisions: repo docs/planning/adr/0003-motion-validation.md; glossary: CONTEXT.md). Regeneration spec: oxmpl - sprint-005. Line references are as of origin/main c558556 (2026-10-08), before E3. E3 renames things (rand Rng→RngExt, PyO3 with_gil→attach, edition 2024), so re-grep before trusting a line number.