Sprint 004 — Motion validator and SpaceInformation (provisional)

Provisional scaffold for release 0.9.0 (E4), written 2026-10-08 so the release isn't lost. Nothing here is committed: the stories carry no oxmpl/sprint/004 tag until planning confirms them against the owner's stated availability. Dates are re-derived at the previous sprint's retro if it slipped.

• Dates (provisional): Thu 2026-11-19 → Wed 2026-12-09 (three weeks)
• Epic: E4 — Validation (0.9.0)
• Goal (provisional): One pluggable motion validator behind SpaceInformation; all ~147 setup call sites migrated — main green, nothing released.

Provisional commitment

• S4.4 — Motion validator trait and discrete validator (size-M; after E3, S4.2, S4.3)
• S4.5 — SpaceInformation migration (size-L; after E3, S4.4)

Order: S4.4 → S4.5. S4.5 is the big break: no feature work mixed in.

Entry criteria: S4.2 and S4.3 done. Pull-forward candidates if capacity allows: S4.6 (needs S4.2), S4.8 (needs S4.3).

Blind pickup: how to (re)generate the tickets

Tickets for these stories already exist in TaskNotes (created 2026-10-08). Once a ticket exists, its TaskNotes details are authoritative and this page is only the regeneration spec. If a ticket is missing or was lost, recreate it from the spec below:

1. tasknotes_create_task with the title, projects, tags and priority shown. MCP quirks: create drops the description and defaults scheduled to today, so follow with tasknotes_update_task to set details (the body below) and scheduled: null.
2. Wire blockedBy by editing the task file's YAML frontmatter directly (no MCP tool exposes it). A story lists all upstream dependencies, including done ones.
3. Verify with tasknotes_get_task: isBlocked: true on the story while its upstreams are open, and isBlocking on each upstream. After any later update_task, re-check that blockedBy survived.
4. If the epic E4 is missing, recreate it first from the spec in oxmpl - sprint-003 § Epic E4.
5. At this sprint's planning (owner confirms availability): add the oxmpl/sprint/NNN tag, set scheduled/due to the sprint dates, remove sprint-status: provisional from this page's frontmatter, and rewrite the "Provisional commitment" heading as "Commitment".

Conventions: oxmpl - planning. Repo context: ADR docs/planning/adr/0003-motion-validation.md (decisions), CONTEXT.md (glossary). 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.

Story specs

S4.4 — Motion validator trait and discrete validator (size-M)

# TaskNotes task — file: task_notes/tasks/S4.4 — Motion validator trait and discrete validator.md
title: "S4.4 — Motion validator trait and discrete validator"
status: open
priority: normal
projects: ["[[E4 Validation — 0.9.0]]"]
tags: [oxmpl, oxmpl/epic, oxmpl/story/size-M]   # add oxmpl/sprint/004 only when committed at planning
scheduled: null      # set to sprint start when committed
due: null            # set to sprint end when committed
blockedBy:           # wire in frontmatter by hand (no MCP tool exposes it)
  - uid: "[[E3 Toolchain refresh — 0.8.0]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.2 — Fallible, thread-safe validation core]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.3 — Space resolution valid segment count]]"
    reltype: FINISHTOSTART

details body:

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.

S4.5 — SpaceInformation migration (size-L)

# TaskNotes task — file: task_notes/tasks/S4.5 — SpaceInformation migration.md
title: "S4.5 — SpaceInformation migration"
status: open
priority: normal
projects: ["[[E4 Validation — 0.9.0]]"]
tags: [oxmpl, oxmpl/epic, oxmpl/story/size-L]   # add oxmpl/sprint/004 only when committed at planning
scheduled: null      # set to sprint start when committed
due: null            # set to sprint end when committed
blockedBy:           # wire in frontmatter by hand (no MCP tool exposes it)
  - uid: "[[E3 Toolchain refresh — 0.8.0]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.4 — Motion validator trait and discrete validator]]"
    reltype: FINISHTOSTART

details body:

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.

Progress log

• 2026-10-08 — Scaffolded as provisional during sprint-002 planning (owner request); expanded the same day into a full regeneration spec (owner request: "enough that a blind pickup can generate all the tickets"). Not yet planned or committed.

Review & retro

At sprint end: done / carried over / dropped, what was over- or underestimated, and at most one process change for the next sprint.