Skip to content

v0.8 development plan — technical maintenance and Python 3.14

R1–R9 and the accepted post-R9 COPYING distribution correction are complete. This plan is archived with the finalized source contract; its original work packages and future-tense implementation detail remain below as development history.

This completed plan records technical work intentionally separated from both the v0.7 API-stabilization release and the later prescribed-measure feature line. v0.8.0 uses the project Git tag, GitHub Release, and PyPI distribution process and intentionally creates no new pyvoro2 Zenodo software-version record. Existing historical pyvoro2 and project/reproducibility Zenodo records remain valid.

Final outcome and release handoff

R1–R9 were completed and independently accepted, and the post-R9 correction that makes wheel and sdist distributions carry and verify COPYING was also completed and accepted. One exact final source commit is independently reviewed and frozen; issue #33 qualifies that exact commit and its artifacts before the public tag is created. Any tracked correction changes the candidate hash and requires renewed review and qualification. No tracked source edit is expected after #33. The release model is Git tag, GitHub Release, and PyPI without a new pyvoro2 Zenodo software-version record.

Intended outcome

v0.8.0 should leave pyvoro2 with one clean forward API, one clean separator inverse API, a navigable test suite, and private Python helpers grouped under an explicit internal package. It also adds standard Python 3.14 support and a complete tested wheel matrix. It is a technical-maintenance release, not a numerical-feature release.

At the end of v0.8:

  • new and existing code use pyvoro2.inverse and pyvoro2.inverse.separator, not pyvoro2.powerfit or top-level separator re-exports;
  • deprecated planar result selectors and aliases are gone;
  • compatibility-only reference and characterization assets have been removed or converted into canonical regression tests;
  • tests are organized by subsystem;
  • root private Python helpers live under pyvoro2._internal;
  • standard Python 3.10–3.14 source installations are tested;
  • binary wheels are built and tested for Linux x86_64, Windows AMD64, macOS arm64, and macOS x86_64;
  • v0.7 stable numerical behavior remains unchanged;
  • deferred non-critical audit findings are either fixed or explicitly carried forward with justification.

Required scope

Compatibility removal

Remove the compatibility-only surfaces listed in ADR 0006 and update:

  • package exports and lazy attribute resolution;
  • direct module imports and pickling compatibility decisions;
  • tests and public examples;
  • API reference navigation;
  • distribution-content checks;
  • migration documentation and changelog;
  • architecture and lifecycle inventories.

Judge retention by clean current architecture and usability. Do not preserve an old route solely because a hypothetical caller might still use it.

Test-suite organization

Organize the test suite into responsibility-based directories. The issue-#29 layout is:

tests/
├── forward/
│   ├── common/
│   ├── spatial/
│   └── planar/
├── inverse/
│   └── separator/
├── integration/
├── tooling/
├── fuzz/
└── conftest.py

The small common-forward area owns dimension-neutral result, weight-input, and public forward contracts; it is not a generic shared-test dumping ground. The move is primarily mechanical and does not combine file movement with numerical test rewrites. Shared imported helpers live in an explicitly owned support module rather than in conftest.py.

Once v0.7-only compatibility tests are removed, a compatibility/ directory is needed only for still-supported cross-version or raw-output contracts.

Private Python helper organization

Move root private helpers such as _cell_output.py, _domain_geometry.py, _face_shifts3d.py, _inputs.py, _power_input.py, _util.py, and _weight_transforms.py under pyvoro2._internal with responsibility-based names or subpackages where useful.

Do not rename the compiled native extensions _core and _core2d merely for visual symmetry. Preserve lazy native loading and verify source and wheel contents after the move.

Planar private helpers may be reviewed at the same time, but no public pyvoro2.core namespace should be introduced.

Python 3.14 and binary distributions

Add standard Python 3.14 support while preserving Python 3.10 as the minimum supported version. Update the build toolchain, package metadata, source-test matrices, and cibuildwheel configuration accordingly.

The required wheel targets are:

  • Linux manylinux x86_64;
  • Windows AMD64;
  • macOS arm64;
  • macOS x86_64;
  • Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Every wheel must be installed and exercised on a compatible runner. Source qualification must include a round trip from generated sdist to rebuilt wheel and installed smoke tests.

Deferred v0.7 audit findings

The initial deferred list includes:

  • narrow overly strong wording around pickle restoration and version independence;
  • exact support and validation expectations for direct TessellationResult(...) construction;
  • external-ID typing versus runtime behavior in separator observations;
  • eager inverse imports caused by v0.7 top-level compatibility exports;
  • release-tool shell-glob portability for twine check;
  • any other non-critical documentation/source mismatch explicitly recorded during v0.7 issue #16 or release qualification.

This list is not permission for unrelated redesign. Each item should be fixed by its smallest coherent change or moved to a named later issue.

Non-goals

v0.8 does not include:

  • prescribed area or volume observations or fitting;
  • mixed separator and cell-measure objectives;
  • new solver families or numerical algorithms;
  • trajectory, repeated-frame, batch, or parallel APIs;
  • site motion, centroid observations, or anisotropic geometry;
  • a public pyvoro2.core namespace;
  • broad source refactoring unrelated to compatibility or private-helper organization;
  • expansion to additional interpreter or platform variants beyond the approved v0.8 support matrix.

Validation

The release should demonstrate that cleanup did not alter stable v0.7 behavior:

  • the full default suite, including seeded fuzz/property tests, plus explicitly increased fuzz counts and dependency-gated cross-checks where relevant;
  • canonical forward and separator workflows only;
  • exact public export inventory after removal;
  • clean source editable installation on the supported Python range;
  • no-SciPy installation and explicit sparse installation;
  • strict docs, notebook, README, sdist, wheel, and smoke checks;
  • sdist-to-wheel round-trip installation;
  • the complete tested Python 3.10–3.14 wheel matrix;
  • comparison of representative v0.7 numerical outputs before and after internal moves;
  • platform coverage sufficient to protect native lazy-loading changes.

Initial issue map

Issue Work package
#24 Activate this plan and its public release contract
#25 Add Python 3.14 build-system and package-metadata support
#26 Test Python 3.14 source installations across supported operating systems
#27 Build and test Python 3.10–3.14 wheels on supported platforms
#34 Modernize GitHub Actions runtimes and runner images
#28 Remove the v0.7 compatibility-only API surfaces
#29 Reorganize the test suite by subsystem
#30 Move private Python helpers under pyvoro2._internal
#31 Resolve deferred v0.7 API and consistency findings
#32 Finalize the v0.8 documentation and public API inventory
#35 Complete final pre-release correctness and safety remediation (R1–R9)
#33 Qualify and release v0.8.0 after #35 closes

This is the initial milestone map rather than a promise that no additional focused issue will be needed. Independent findings discovered during implementation should be split into named issues instead of silently expanding an existing work package.

Pre-release audit remediation

The original maintenance work reached a green ordinary test state, but the final pre-release audit found correctness and native-safety defects outside the existing regression envelope. These findings do not change v0.8 into a feature release. They create a required remediation workstream under GitHub issue #35.

The integrated audit records evidence and paste-ready R1–R9 child-issue contracts. The remediation execution plan defines dependency order, implementation/review workflow, regression ledgers, and the handoff to final release qualification. Issue #33 is blocked until #35 is closed.

This work remains within the technical-maintenance scope: it corrects documented behavior, prevents invalid inputs from reaching unsafe native paths, certifies periodic geometry used by existing APIs, restores result/diagnostic integrity, and synchronizes the release contract. Prescribed measures and other new numerical families remain out of scope.

Later releases

  • v0.9 performs functional/API stabilization and downstream-readiness work without adding a new inverse observation family.
  • 1.0 stabilizes the existing forward and separator-inverse core after downstream qualification.
  • v1.1 introduces prescribed cell areas and volumes.
  • v1.2 introduces the first mixed separator-plus-measure inverse problems.

None of this later work should be pulled into the v0.8 cleanup plan.