S4.7 — User motion validators in the bindings

Intent

Let Python and JS users validate a whole motion in one cross-language call (vectorised NumPy checks, physics-engine continuous collision, swept volumes) instead of one call per interpolated state. This is the main performance win of 0.9.0 for binding users.

Decisions (ADR-0003; grilling Q14)

• A user motion validator is a duck-typed object, not a callable and not a required base class: Python check_motion(s1, s2) -> bool, JS checkMotion(s1, s2) -> boolean.
• Verified when set (set_motion_validator / constructor kwarg): a missing method raises ConfigurationError immediately, not mid-solve.
• Later optional methods (e.g. a last-valid variant) are detected by presence (hasattr / property check) so they can be added without breaking anyone.
• Strict return types: Python accepts bool and NumPy bool_ (pyo3 extraction already handles it); anything else, including None, raises. JS: non-boolean raises (replacing today's console.warn + false behaviour).
• One generic adapter per binding (via PyStateConvert / JsStateConvert), not one per state type.
• Type hints: Python typing.Protocol stub (MotionValidator), TypeScript interface MotionValidator.
• Exposing the built-in discrete validator as a wrappable object is not in scope (YAGNI; additive later).

Acceptance criteria

• Python: SpaceInformation(..., motion_validator=obj) and si.set_motion_validator(obj) accept duck-typed objects; missing method raises at set time
• JS: si.setMotionValidator(obj) same semantics
• Strict return check in both bindings (tests for None, 0, "true" raising; NumPy bool_ accepted)
• Errors raised inside the user's check_motion propagate per S4.6 (original exception)
• A user validator drives all four planners in both bindings (test per planner, at least one space)
• Demonstration test: a user validator that never calls back per state is used instead of the discrete one (count Python/JS calls)
• Python Protocol stub shipped in the package; TypeScript interface in index.d.ts
• just test-all green

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