Sprint 006 — Release 0.9.0 "Validation" (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/006 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-12-31 → Wed 2027-01-20 (three weeks)
• Epic: E4 — Validation (0.9.0)
• Goal (provisional): v0.9.0 published on crates.io, PyPI and npm with a migration guide.

Provisional commitment

• S4.7 — User motion validators in the bindings (size-M; after E3, S4.5, S4.6)
• S4.9 — Docs, migration guide, ADR-0003 accepted (size-M; after E3, S4.1, S4.2, S4.3, S4.4, S4.5, S4.6, S4.7, S4.8)
• S4.10 — Release 0.9.0 (size-S; after E3, S4.1, S4.2, S4.3, S4.4, S4.5, S4.6, S4.7, S4.8, S4.9)

Order: S4.7 → S4.9 → S4.10.

Entry criteria: S4.1–S4.6 and S4.8 done. After the release: close E4 and run release planning for 0.10.0 "Path Quality" (scope in oxmpl - backlog; no epic exists yet).

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.7 — User motion validators in the bindings (size-M)

# TaskNotes task — file: task_notes/tasks/S4.7 — User motion validators in the bindings.md
title: "S4.7 — User motion validators in the bindings"
status: open
priority: normal
projects: ["[[E4 Validation — 0.9.0]]"]
tags: [oxmpl, oxmpl/epic, oxmpl/story/size-M]   # add oxmpl/sprint/006 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.5 — SpaceInformation migration]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.6 — Binding error hierarchy]]"
    reltype: FINISHTOSTART

details body:

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

S4.9 — Docs, migration guide, ADR-0003 accepted (size-M)

# TaskNotes task — file: task_notes/tasks/S4.9 — Docs, migration guide, ADR-0003 accepted.md
title: "S4.9 — Docs, migration guide, ADR-0003 accepted"
status: open
priority: normal
projects: ["[[E4 Validation — 0.9.0]]"]
tags: [oxmpl, oxmpl/epic, oxmpl/story/size-M]   # add oxmpl/sprint/006 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.1 — PRM milestone budget]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.2 — Fallible, thread-safe validation core]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.3 — Space resolution valid segment count]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.4 — Motion validator trait and discrete validator]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.5 — SpaceInformation migration]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.6 — Binding error hierarchy]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.7 — User motion validators in the bindings]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.8 — Resolution exposed in the bindings]]"
    reltype: FINISHTOSTART

details body:

Intent

Document the 0.9.0 model and give users one migration path for all its breaking changes.

Acceptance criteria

• docs/src/concepts.md: state validity vs motion validation, resolution vs checking strategy, SpaceInformation, milestones (terms from CONTEXT.md)
• docs/src/guides/validity_checkers.md and guides/goals.md: fallible signatures, Send + Sync, error behaviour
• New guide: writing a motion validator (Rust, Python, JS) — including the "s1 assumed valid" contract and a batched/vectorised example
• docs/src/python_api.md / js_api.md: SpaceInformation, motion validators, error classes, resolution methods, max_milestones
• docs/src/contributing/implementing_planners.md / implementing_state_spaces.md: valid_segment_count, using the motion validator, setup(problem_def)
• All six example pages (docs/src/examples/*) match the updated example programs
• Migration guide 0.8 → 0.9 listing every breaking change with before/after snippets in three languages:
  • fallible is_valid / is_satisfied / distance_goal (Ok(..))
  • Send + Sync on checkers, spaces, goals (Rc/RefCell → Arc/Mutex)
  • PlanningError non-exhaustive, no PartialEq, new User variant
  • default fraction 0.05 → 0.01 and no ×0.1 (set 0.005 for the old single-space spacing)
  • SpaceInformation + ProblemDefinition + setup(pd); bindings drop setup; JS StateValidityChecker removed
  • binding exceptions; JS setter rename
  • spaces shared and frozen once used
• ADR-0003 status: accepted (repo docs/planning/adr/0003-motion-validation.md)
• Every breaking commit in the release range carries a BREAKING CHANGE: footer (check git log v0.8.0..)
• mdbook build docs clean

S4.10 — Release 0.9.0 (size-S)

# TaskNotes task — file: task_notes/tasks/S4.10 — Release 0.9.0.md
title: "S4.10 — Release 0.9.0"
status: open
priority: normal
projects: ["[[E4 Validation — 0.9.0]]"]
tags: [oxmpl, oxmpl/epic, oxmpl/story/size-S]   # add oxmpl/sprint/006 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.1 — PRM milestone budget]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.2 — Fallible, thread-safe validation core]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.3 — Space resolution valid segment count]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.4 — Motion validator trait and discrete validator]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.5 — SpaceInformation migration]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.6 — Binding error hierarchy]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.7 — User motion validators in the bindings]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.8 — Resolution exposed in the bindings]]"
    reltype: FINISHTOSTART
  - uid: "[[S4.9 — Docs, migration guide, ADR-0003 accepted]]"
    reltype: FINISHTOSTART

details body:

Intent

Cut 0.9.0 "Validation" on all three registries through the tokenless publishing set up in E3 (S3.4).

Acceptance criteria

• Release-please PR proposes v0.9.0
• Published: crates.io (oxmpl, oxmpl-py, oxmpl-js), PyPI (oxmpl-py wheels + sdist), npm (oxmpl-js)
• GitHub release notes present and link the migration guide
• Installable: pip install oxmpl-py==0.9.0, npm view oxmpl-js@0.9.0, crates.io 0.9.0
• Post-release: main's workflows green

Tasks

• Manually trigger the release workflows once before tagging (no publish)
• Merge the release-please PR; confirm 0.9.0
• Watch CI through publish; verify installs
• Record release friction in the sprint page
• After release: close E4, move "Robust binding errors" backlog entry to Completed, run release planning for 0.10.0 "Path Quality"

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.