S4.2 — Fallible, thread-safe validation core

Intent

User-supplied validation code can fail, and today that failure is invisible. Probe against oxmpl-py 0.7.0 (2026-10-08): a Python checker that raised was printed and treated as "invalid", so solve() still returned a path; KeyboardInterrupt was swallowed; a typo (s.valuez) produced 286k traceback lines over the full timeout and then a misleading "No solution found". OMPL's Python bindings raise immediately because C++ exceptions unwind through the planner; Rust has no such channel (and the wasm build is panic="abort"), so the error must be in the signature. Make failure a first-class error and make the validation traits thread-safe in one breaking change.

Decisions (ADR-0003; grilling Q4/Q5/Q6/Q7/Q18)

• UserError = Box<dyn std::error::Error + Send + Sync>: any Rust error converts with ?; bindings box the original PyErr / JsValue so S4.6 can re-raise it.
• Fallible: StateValidityChecker::is_valid -> Result<bool, UserError>, Goal::is_satisfied -> Result<bool, UserError>, GoalRegion::distance_goal -> Result<f64, UserError>. GoalSampleableRegion::sample_goal keeps its signature (already Result<S, StateSamplingError>).
• PlanningError: add User(UserError); remove PartialEq (boxed errors are not comparable; tests already use matches!); add #[non_exhaustive].
• StateSamplingError: add User(UserError); add #[non_exhaustive] (and drop PartialEq if User makes it impossible).
• Thread safety: StateValidityChecker, StateSpace (including AnyStateSpace and the boxed compound subspaces), and the goal traits all become Send + Sync. Needed because the motion validator (S4.4) holds the space and checker and must be Send + Sync; adding the bound later would be a second breaking change.
• JS: js_sys::Function / JsValue are never Send/Sync. Adapters use unsafe impl Send + Sync, which is sound only on single-threaded wasm32; guard with #[cfg(target_feature = "atomics")] compile_error!(...).
• Python: Py<T> is already Send + Sync (pyo3), so no unsafe needed.
• Planners abort on the first user error with PlanningError::User(..); no retry, no logging-and-continue.

Acceptance criteria

• Trait signatures changed as above; UserError exported from oxmpl::base::error
• PlanningError::User, StateSamplingError::User; both enums #[non_exhaustive]; PlanningError no longer PartialEq
• Send + Sync supertraits on StateValidityChecker, StateSpace, AnyStateSpace, Goal (and hence GoalRegion, GoalSampleableRegion)
• Each of the four planners has a test: a checker that returns Err on the Nth call makes solve() return ErrUser(_)) promptly (well before the timeout; same for a failing goal
• Python and JS adapters return Err carrying the original exception/value instead of printing and returning false / INFINITY / GoalRegionUnsatisfiable (raising it to the user is S4.6; here it only has to propagate and surface as some error)
• JS unsafe impl guarded by the atomics compile_error!
• oxmpl/tests/seeded_rng_tests.rs test doubles migrated from Rc/RefCell/Cell to Arc/Mutex/atomics; RNG-stream guards still pass
• just test-all green; clippy clean
• Commit carries a BREAKING CHANGE: footer

Tasks

• oxmpl/src/base/error.rs: add UserError, the User variants, #[non_exhaustive], adjust derives and Display
• oxmpl/src/base/validity.rs (trait :39), goal.rs (:12/:21/:32), space.rs (:80), spaces/any_state_space.rs (:45): signatures and bounds
• Planner call sites with ?: is_valid 10 (prm 4, rrt_connect 2, rrt 2, rrt_star 2), is_satisfied 8, distance_goal 4. Watch closures/iterators in RRT* rewiring; refactor to loops where ? cannot cross a closure
• Inside the private check_motion copies (rrt.rs:96, prm.rs:179, rrt_star.rs:89, rrt_connect.rs:172) propagate Result<bool, UserError> (S4.4 deletes these later)
• Update every implementor to return Ok(..): StateValidityChecker impls — src 6, tests 25, examples 2, py 6, js 6, docs 1; Goal/GoalRegion impls — src 4, tests 25, examples 2, py 1 (generic), js 6, docs 1
• Python adapters: oxmpl-py/src/base/state_validity_checker.rs (6 impls; currently e.print(py); false), goal.rs (unwrap_or(false), unwrap_orINFINITY), sample_goal prints and returns GoalRegionUnsatisfiable
• JS adapters: oxmpl-js/src/base/state_validity_checker.rs error_2 + false; non-boolean → console::warn_1 + false), goal.rs (console::error_2
• Binding planners: map PlanningError::User to some exception/thrown value for now (typed in S4.6)
• Migrate seeded_rng_tests.rs doubles (Rc<Samples> :62/:101/:132, RefCell :26, Cell :27)
• Update docs/src/guides/validity_checkers.md, guides/goals.md, contributing/implementing_state_spaces.md, contributing/implementing_planners.md for the new signatures

Risks

• Highest: the Send + Sync cascade through Box<dyn AnyStateSpace> (compound_state_space.rs:53) may collide with the ADR-0002 two-tier State/AnyState split. If it spreads beyond adding bounds, stop and raise it with the owner before redesigning.
• ? inside iterator chains in rrt_star.rs needs local refactors.

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-003. 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.