S4.1 — PRM milestone budget

Intent

PRM builds its roadmap until a wall-clock timeout, so roadmap density depends on machine speed and on how expensive each validity call is. In the bindings every check crosses into Python/JS (~122k calls/s measured on pyo3), which caused the deterministic py SO(3) failure and the JS compound flake root-caused during S1.4. Add an additive milestone budget: with a seed, a budget and a deterministic checker, a roadmap becomes reproducible. Supersedes S2.1 (cancelled). Goes first in E4 because S4.3/S4.4 change the motion-check resolution, which would destabilise wall-clock-bound PRM tests.

Decisions (grilling 2026-10-08, Q3/Q17/Q19)

• Additive, not breaking: Rust PRM has private fields (no struct-literal construction), so a new public field is safe.
• A milestone is a valid sample added to the roadmap; rejected samples do not count (glossary: CONTEXT.md § Roadmaps).
• Construction stops at the budget or the timeout, whichever first. The timeout stays the safety cap. This amends S1.3's "timeout-only, no iteration API" for PRM construction only; no ADR (additive and easy to reverse).
• milestone_count() getter, as OMPL's PRM::milestoneCount().

Acceptance criteria

• Rust: pub max_milestones: Option<usize> on PRM (default None = today's behaviour); PRM::new signature unchanged
• Python: PRM(..., max_milestones=None) keyword argument
• JS: optional trailing constructor argument maxMilestones (undefined = none); TypeScript type updated
• construct_roadmap stops when roadmap.len() == max_milestones or the timeout passes, whichever first
• milestone_count() in Rust, milestone_count() in Python, milestoneCount() in JS
• Reproducibility test (Rust): same seed + same budget + deterministic checker ⇒ identical roadmap (states and edges), built twice
• Budget-reached test: with a generous timeout, milestone_count() == max_milestones after construction
• All PRM tests in the three crates use a budget (with a generous timeout as cap), so pass/fail no longer depends on machine speed
• S1.4's set_longest_valid_segment_fraction(0.25) workarounds removed where the budget makes them unnecessary
• just test-all green

Tasks

• Add the field and the stop condition in construct_roadmap (oxmpl/src/geometric/planners/prm.rs: struct :53, new :75, loop :123)
• Add milestone_count(); consider resolving the get_roadmap TODO (:87) only if needed for the reproducibility test
• Python binding: kwarg + getter (oxmpl-py/src/geometric/prm.rs, constructor :60)
• JS binding: optional arg + getter (oxmpl-js/src/geometric/prm.rs, constructor :43); oxmpl-js/index.d.ts if hand-written types need it
• Convert PRM tests: oxmpl/tests/prm_*_tests.rs (6), oxmpl-py/tests/test_prm_*.py (6), oxmpl-js/tests/test_prm_*.test.js (6)
• Remove workarounds: oxmpl-py/tests/test_prm_so3ss.py:55, oxmpl-js/tests/test_prm_compound.test.js:34-35
• Add milestone usage to docs/src/python_api.md / js_api.md PRM sections
• Conventional commit feat(prm): ... (not breaking)

Risks

• A budget too high for the timeout silently falls back to timeout behaviour; tests should assert the budget was reached, not just that a path was found.

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.