Skip to content

0006 — v0.8 is a cleanup-only compatibility-removal release

Context

v0.7 deliberately retains one bounded transition layer while establishing the canonical forward and separator APIs. The project has very few users, the pre-1.0 API has always been described as unstable, and known downstream use is limited mainly to the direct forward Voronoi functionality.

Carrying transitional imports and selectors farther would preserve historical shapes at the expense of a clearer package. The same release boundary is also a good opportunity for internal organization work that would be unnecessarily noisy during the v0.7 contract-finalization issue.

Prescribed cell measures and mixed separator-plus-measure fitting are important future features, but combining either feature with compatibility removal and source-tree reorganization would make the release difficult to review and qualify.

Decision

v0.8 will be a cleanup-only release. It will not add a new inverse observation family or other user-facing numerical feature.

Its planned work is:

  1. remove the v0.7 compatibility-only inverse package, top-level inverse re-exports, historical core aliases, planar result alias, and deprecated planar return selector;
  2. audit every remaining compatibility path and retain only routes that are useful as current API rather than merely historical behavior;
  3. reorganize the flat test suite into responsibility-based subdirectories without changing numerical behavior;
  4. move private Python helpers from the root src/pyvoro2/_*.py collection into a private pyvoro2._internal package, while leaving compiled extension names such as _core and _core2d unchanged;
  5. resolve non-critical consistency and maintenance findings deferred from the v0.7 final audit;
  6. preserve the stable v0.7 forward and high-level separator contracts unless a separately approved correctness fix requires change.

The v0.7 compatibility horizon is therefore final: removal in v0.8 does not require evidence of user breakage or a usage-based extension decision. The cleanup should be judged by current architecture, usability, and maintenance cost.

The feature sequence becomes:

  • v0.8: cleanup and compatibility removal;
  • v0.9: prescribed cell areas/volumes;
  • v0.10: mixed separator and cell-measure inverse problems.

Compatibility surfaces scheduled for removal

The v0.8 audit starts from these known v0.7-only surfaces:

  • pyvoro2.powerfit and all of its historical direct submodules;
  • broad separator-specific exports from top-level pyvoro2;
  • historical separator names exported from pyvoro2.inverse.separator, including the five core identity aliases;
  • the lazy top-level pyvoro2.powerfit attribute;
  • pyvoro2.planar.PlanarComputeResult and pyvoro2.planar.result.PlanarComputeResult;
  • planar return_result=;
  • compatibility tests and reference pages whose only purpose is to preserve those routes.

output='cells' is not scheduled for automatic removal. It is an explicit, useful raw-data output mode in the current forward API, not merely a hidden legacy switch. The v0.8 audit may simplify its documentation, but removal would require a separate API decision.

Consequences

  • v0.7 remains the only release carrying the inverse migration shim.
  • v0.8 can simplify package imports, __all__, distribution checks, tests, and reference navigation before new inverse families are introduced.
  • Test and private-module moves are reviewable as mechanical refactors because they are not mixed with prescribed-measure solver work.
  • Prescribed-measure design can start from the cleaned canonical architecture in v0.9.
  • Mixed-observation protocol design remains evidence-driven and waits until both real observation families exist in v0.10.

Alternatives considered

Add prescribed measures in v0.8 while removing compatibility

Rejected. A new nonlinear inverse family and a broad cleanup release have independent risks and should not share one qualification boundary.

Keep compatibility until 1.0

Rejected. The project is pre-1.0, has negligible dependence on the historical inverse API, and would gain little from maintaining a second public vocabulary.

Remove the raw cell output together with all historical behavior

Rejected as a blanket rule. Raw cells remain useful for low-level geometry and are already exposed through the explicit current selector output='cells'.