S4.4 — Motion validator trait and discrete validator

Intent

Motion validation is today four private check_motion copies with a hidden ×0.1 oversampling factor (each step is longest_valid_segment_length × 0.1). Replace them with a public, pluggable MotionValidator and a default DiscreteMotionValidator, modelled on OMPL. Planners build the default internally in this story; how users attach their own validator is S4.5. Supersedes the rest of S2.2 (cancelled).

Decisions (ADR-0003)

• Glossary (CONTEXT.md § Validity): a motion is the transition traced by the space's interpolate; motion validation decides whether every state along it is valid, assuming the start is valid; resolution is owned by the space; checking strategy is owned by the validator, which may ignore the space's resolution.
• Trait: pub trait MotionValidator<S: State>: Send + Sync { fn check_motion(&self, s1: &S, s2: &S) -> Result<bool, UserError>; }. Object-safe (used as Arc<dyn MotionValidator<S>>).
• The trait docs state from day one that s1 is assumed valid (needed so a later last-valid method can default soundly).
• Exactly one required method. OMPL's second overload (last valid state + fraction) is deferred; when a planner needs it, it arrives as a provided method check_motion_last_valid(&self, s1, s2) -> Result<Result<(), f64>, UserError> (exact shape decided then) defaulting to Err(0.0) on failure. Do not add it now.
• No valid/invalid counters in the trait (a decorating validator can count later).
• DiscreteMotionValidator holds the space and the state validity checker; uses the space's valid_segment_count (S4.3); checks s2 first, then interior states in bisection (BFS-midpoint) order, as OMPL's DiscreteMotionValidator::checkMotion(s1, s2). Linear order is the cut-fallback if bisection slips.
• The default validator is always the discrete one; per-space defaults (e.g. Dubins) may come later as a provided StateSpace method.

Acceptance criteria

• MotionValidator trait public in oxmpl::base (new module, e.g. base/motion_validator.rs)
• DiscreteMotionValidator<S, SP> public, constructed from Arc<SP> and Arc<dyn StateValidityChecker<S>>
• The four private check_motion copies are deleted; planners call the validator (built internally from the problem definition's space and the checker passed to setup)
• The ×0.1 factor no longer exists anywhere (rg "\* 0\.1" in planners is empty)
• Tests: a thin obstacle narrower than the resolution is missed and one wider is caught (documents the semantics); bisection visits states in the expected order (instrumented checker); s2 is checked first; a checker Err propagates as Err
• Planner tests across all spaces still pass after the effective resolution change (geometry adjusted only where a test relied on ×0.1 oversampling; note each such change in the PR)
• just test-all green; commit marked breaking (collision-checking behaviour changes)

Tasks

• New module + re-export from oxmpl/src/base/mod.rs
• Implement DiscreteMotionValidator (OMPL reference: src/ompl/base/src/DiscreteMotionValidator.cpp, the two-argument checkMotion with the std::queue<std::pair<int,int>> bisection)
• Replace the 7 check_motion call sites: rrt.rs:218, prm.rs:152 and :270, rrt_star.rs:235, :258, :290, rrt_connect.rs:155
• Delete the four copies (rrt.rs:96, prm.rs:179, rrt_star.rs:89, rrt_connect.rs:172)
• Rustdoc with the "s1 assumed valid" contract and a short example implementing a custom validator

Risks

• Behaviour drift: tests with tight geometry may start passing or failing differently because effective resolution changes (2× coarser for single spaces, finer for compound). S4.1's budgets absorb the PRM side; check RRT-family tests individually.

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