S4.5 — SpaceInformation migration

Intent

Introduce SpaceInformation — the state space plus the state validity checker plus the motion validator — as the single source of validity, so planners and the future path simplifier (0.10.0) can never judge validity differently. This is 0.9.0's big breaking change; do it alone, with no feature work mixed in.

Decisions (ADR-0003; grilling Q1/Q8/Q9/Q9′/Q10/Q11/Q12)

• Name SpaceInformation, as in OMPL (glossary: CONTEXT.md § Validity, "Space information").
• SpaceInformation::new(space: Arc<SP>, checker: Arc<dyn StateValidityChecker<S>>) — the checker is required (OMPL silently installs an all-valid checker; we don't). The discrete motion validator is installed by default.
• set_motion_validator(&mut self, mv: Arc<dyn MotionValidator<S>>) keeps OMPL's name but needs exclusive access: configure first, then share as Arc<SpaceInformation<..>>. Once shared it is frozen — this prevents a PRM roadmap built under one validator being queried under another (a silent hazard in OMPL's mutable model) and keeps locks off the hottest path.
• ProblemDefinition holds Arc<SpaceInformation<..>> instead of its pub space field. Exactly one path to the space.
• Planner::setup(&mut self, problem_def) — the checker argument goes. Bindings drop setup entirely: their planner constructors already receive the problem definition.
• Bindings: Python SpaceInformation(space, is_valid_fn, motion_validator=None); JS new SpaceInformation(space, isValidFn) plus setMotionValidator. JS's StateValidityChecker wrapper class is removed. The checker stays a plain function in both bindings.
• Binding setters use Arc::get_mut; if a ProblemDefinition already holds the SpaceInformation, raise "SpaceInformation is already used by a ProblemDefinition; configure it first" (typed as ConfigurationError once S4.6 lands).
• Binding spaces are shared, not copied: today ProblemDefinition constructors snapshot the space (lock().unwrap().clone() — py 3 sites, js 6 sites), so configuring a space afterwards is a silent no-op. After this story, mutating a space already used by a SpaceInformation raises the same "already in use" error.
• Out of scope (additive later): reusing a PRM roadmap across problem definitions sharing one SpaceInformation ptr_eq.

Acceptance criteria

• SpaceInformation in oxmpl::base with new, set_motion_validator, accessors for space, checker, validator, and convenience is_valid / check_motion
• ProblemDefinition has no space field; constructors/fields take the SpaceInformation (struct literals at 35 sites in oxmpl src/tests/examples migrated)
• Planner::setup(problem_def); all four planners read checker and validator from the SpaceInformation
• All ~147 setup call sites migrated: oxmpl/src 5, oxmpl/tests 30, oxmpl/examples 2, oxmpl-py 54, oxmpl-js 54, docs 2
• Python: SpaceInformation class; ProblemDefinition.from_* (6) take it; planners have no setup; config-after-share raises
• JS: SpaceInformation class; ProblemDefinition.from*State (6) take it; StateValidityChecker class removed; planners have no setup; config-after-share throws; index.d.ts updated
• Space sharing: binding wrappers stop cloning the space into the problem definition; a test proves that mutating a shared space raises instead of silently doing nothing
• Examples (simple_2d_planning, compound_state_planning in all three languages) updated
• just test-all green; commit marked breaking

Tasks

• oxmpl/src/base/space_information.rs (new) + re-export
• oxmpl/src/base/problem_definition.rs (fields :17–:19)
• oxmpl/src/base/planner.rs (setup :42) and the four planners' setup impls
• Python: new oxmpl-py/src/base/space_information.rs; problem_definition.rs (from_real_vector :68, from_so2 :96, from_so3 :124, from_compound :153, from_se2 :182, from_se3 :211); remove setup in oxmpl-py/src/geometric/{rrt:115, rrt_connect:120, rrt_star:129, prm:119}; register class in lib.rs
• JS: new oxmpl-js/src/base/space_information.rs; problem_definition.rs (6 from*State); remove oxmpl-js/src/base/state_validity_checker.rs class (keep the adapter logic inside SpaceInformation); remove setup in oxmpl-js/src/geometric/{rrt:78, rrt_connect:102, rrt_star:109, prm:102}
• Space wrappers are Arc<Mutex<..>> (9 sites); share the Arc instead of cloning the inner space; reject mutation while shared
• Mechanical migration of tests: oxmpl/tests/*.rs (25 files), oxmpl-py/tests/*.py (26), oxmpl-js/tests/*.test.js (26)
• Docs snippets in docs/src/ (2 setup calls plus examples pages)

Risks

• Scale: mechanical but large; keep the PR to the migration only. Consider a codemod (sed/ast-grep) for the test suites.
• Python/JS API shape is public and permanent until 0.10.0 — get names right in this PR.

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.