v0.7 development plan — forward and separator API stabilization

• Status: Completed
• Plan revision: 1.4
• Target release: v0.7.0
• Base release: v0.6.3
• Integration branch: dev
• Maintainer: Ivan Yu. Chernyshov
• Scope approved: 2026-07-17
• Activated: 2026-07-18
• Last revised: 2026-07-23
• Released: 2026-07-23
• Release model: Git tag and PyPI distribution; no GitHub Release or Zenodo record
• GitHub milestone: v0.7 milestone

This plan translates the project roadmap and accepted architecture decisions into an implementation contract for v0.7. It is written for both human contributors and issue-scoped coding-agent work.

Completed plan

This archived plan records the approved v0.7.0 scope, implementation path, final release-source qualification, and deferrals. Remaining external release operations are tracked explicitly in the linked checklist.

Intended outcome

v0.7.0 should make pyvoro2 a dependable foundation for chemvoro and for later inverse weighted-tessellation methods.

At release, a downstream package should be able to:

1. define 2D or 3D sites, domains, and external IDs without private parsing or record-order assumptions;
2. compute a power diagram directly from mathematical power weights;
3. receive one clear structured result type from both forward namespaces;
4. inspect cells, cell measures, empty-cell state, realized boundaries, periodic image labels, and diagnostics through documented public accessors;
5. fit weights from separator observations through a math-aligned pyvoro2.inverse API;
6. distinguish global gauge, unidentified offsets between disconnected observation components, algebraic residuals, realized geometry, and solver state;
7. inspect the graph/Laplacian ingredients of the fixed-observation quadratic problem without reading private solver code;
8. export documented records or reports without relying on internal modules;
9. migrate v0.6.3 separator and raw-result workflows through explicit v0.7 compatibility paths.

The release stabilizes a clear forward and separator contract. It does not freeze a generic inverse framework before a second observation family exists.

Baseline and motivation

The v0.6.3 baseline already provides:

• explicit 3D and planar 2D namespaces;
• bounded and periodic domains;
• standard and power/Laguerre tessellations;
• periodic face/edge image labels;
• diagnostics, normalization, annotations, locate, and ghost_cells;
• separator-observation fitting with graph/connectivity diagnostics, robust and hard constraints, problem export, realization matching, active-set refinement, and report generation.

The main limitations are architectural:

• 3D normally returns raw cell records, while planar computation has an optional PlanarComputeResult;
• forward power computation is radius-first even though the mathematics is weight-first;
• separator implementation is owned by pyvoro2.powerfit and broadly re-exported from top-level pyvoro2;
• current names describe the historical implementation more than the observation model;
• rich inverse diagnostics are not yet organized around a deliberate long-term result vocabulary;
• chemvoro would still need to understand representation shifts, record order, or result-shape details that should belong to pyvoro2.

Adding prescribed cell measures before resolving these boundaries would either duplicate geometry/result handling or freeze an over-general abstraction. v0.7 therefore focuses on the forward result, weight-first computation, separator organization, and public diagnostic contract.

Accepted decisions

The following decisions govern implementation and should not be reopened inside an issue unless new evidence shows a concrete contradiction.

Project and mathematical boundaries

• ADR 0001 — Project scope and layering
• ADR 0002 — Weights, radii, gauge, and component offsets
• ADR 0003 — Compatibility-first API evolution
• ADR 0006 — v0.8 cleanup and compatibility removal

D-07-1 — Canonical inverse namespace: resolved

ADR 0004 establishes:

• pyvoro2.inverse as the canonical inverse namespace;
• pyvoro2.inverse.separator as the owner of separator implementation;
• pyvoro2.powerfit as a one-way compatibility-only shim for v0.7;
• fixed removal of powerfit and broad top-level separator exports in v0.8;
• preferred names including SeparatorObservations, SeparatorFitResult, and fit_weights_from_separators;
• neutral ownership of weight/radius transforms outside separator code.

D-07-2 — Common forward result: resolved

ADR 0005 establishes:

• one public dimension-neutral pyvoro2.TessellationResult;
• a structured result as the default from spatial and planar compute;
• output='result'|'cells' as the preferred return selector;
• PlanarComputeResult and older return switches as compatibility-only paths;
• no list emulation by TessellationResult;
• structural immutability where straightforward, without deep-freezing or defensively copying raw nested records solely for immutability.

D-07-3 — Lifecycle inventory: accepted process, pre-release gate

The inventory method and preliminary categories are recorded in docs/development/api-inventory.md. The inventory is updated during implementation and must be approved before the release candidate. It cannot be postponed until after v0.7, because the release creates the compatibility promise.

D-07-4 — Manuscript figures and references: deferred follow-up issue

Theory figures and literature synchronization are not a v0.7 blocker. Create a separate issue with the working title:

Integrate finalized manuscript figures and references into the theory documentation

The issue should be acted on after the manuscript reaches a stable final public form. It should cover original repository-owned figures, selected references, terminology synchronization, and the final preprint/publication link. Do not copy figures from an intermediate manuscript draft.

Required scope

v0.7 requires:

• characterization of the v0.6.3 public baseline before refactoring;
• a maintained public API lifecycle inventory;
• neutral weight/radius conversion ownership;
• direct weights= input in both forward namespaces;
• one TessellationResult default return contract in 2D and 3D;
• aligned site/ID, measure, empty-cell, representation, and diagnostic access;
• explicit supported raw output;
• physical implementation ownership under pyvoro2.inverse.separator;
• canonical separator names and a concise preferred high-level API;
• one-way pyvoro2.powerfit and top-level compatibility aliases for v0.7;
• explicit deprecation/removal documentation for v0.8;
• layered separator result/diagnostic access;
• inspectable graph, incidence, and quadratic-operator data;
• paper-style regression coverage through public, deterministic repository-owned assets;
• a chemistry-neutral, chemvoro-shaped downstream integration workflow;
• reproducible Jupyter-semantic notebook execution with committed outputs and deterministic, non-executing Markdown export;
• migration documentation, reference updates, release notes, and complete release validation.

The optional SciPy sparse-direct quadratic path is included after the required benchmark and review. It remains restricted to large static quadratic separator graphs and keeps dense and no-SciPy installations complete.

Non-goals

v0.7 does not include:

• prescribed area or volume inversion;
• a public generic ObservationBlock protocol;
• mixed separator and cell-measure objectives;
• site-coordinate optimization;
• centroid, section, anisotropic, spherical, or non-Euclidean observations;
• arbitrary user-defined nonlinear objective callbacks;
• GPU acceleration;
• a persistent mutable tessellation model;
• deep immutability of backend-shaped nested cell records;
• a general computational-geometry abstraction over Voro++;
• guaranteed convergence of the realization-aware active-set loop;
• planar oblique-periodic support solely for 2D/3D symmetry;
• migration of the archived v0.6.3 paper environment;
• notebook execution during an ordinary MkDocs build;
• notebook tooling as a pyvoro2 runtime dependency;
• a general rich-output normalization framework;
• manuscript figure synchronization before the manuscript itself is final.

Implementation principles

1. Characterize before moving. Add tests for undocumented behavior that must survive before reorganizing modules or defaults.
2. One numerical implementation. Compatibility packages import or delegate; they never copy solver formulas.
3. Preferred behavior is explicit. Do not preserve ambiguity by making the new result silently impersonate a list.
4. Scientific semantics are API. IDs, units, global gauge, component offsets, periodic images, empty cells, and realization status require tests.
5. No false dimensional parity. Use one result class, but keep unsupported 2D/3D capabilities visibly absent.
6. Immutability is pragmatic. Use frozen containers and read-only arrays when clean; do not add deep-copy/freeze machinery that obscures the API or delays the release.
7. Sparse scope stays narrow. The included optional SciPy path is limited to large static quadratic separator graphs; it does not imply dynamic or all-branch scalability.
8. Issues define outcomes, not line-by-line code. The implementer may choose clean internal details that satisfy ADRs, public behavior, tests, and scope.
9. Notebook execution and export remain separate. Source notebooks store reviewed outputs produced with Jupyter semantics; Markdown export renders those outputs deterministically without executing native code.

Work packages

ID	Work package	Required?	Depends on
WP-01	Baseline characterization and API inventory	Yes	—
WP-02	Neutral weight transforms and weight-first forward API	Yes	WP-01
WP-03	Common TessellationResult and output migration	Yes	WP-01; coordinate with WP-02
WP-04	Canonical inverse implementation ownership	Yes	WP-01, neutral transforms from WP-02
WP-05	Canonical separator names and compatibility shims	Yes	WP-04
WP-06	Separator result layering and algebraic operator access	Yes	WP-04, WP-05; coordinate with WP-03
WP-09	Sparse quadratic benchmark and execution	Yes	WP-06
WP-07	Paper-style and chemvoro-shaped integration validation	Yes	WP-02–WP-06; WP-09
WP-07A	Reproducible notebook execution and published outputs	Yes	WP-07
WP-08	Lifecycle inventory, migration, and documentation finalization	Yes	WP-02–WP-07; WP-07A
WP-10	Release qualification and plan completion	Yes	All required packages

WP-01 — Baseline characterization and API inventory

Purpose: establish the factual v0.6.3 compatibility baseline and create the issue graph before public behavior changes.

Status: Completed by #6. The exact observed surface is recorded in the API inventory and focused compatibility tests.

Deliverables:

• enumerate documented exports, signatures, defaults, return variants, record keys, result/report fields, and __all__ contents;
• update the draft API inventory with exact baseline data;
• identify behavior already protected by tests and add focused characterization tests for unprotected compatibility cases;
• record a small chemvoro-shaped requirement set without introducing chemistry policy into core APIs;
• create the v0.7 milestone and issue dependency graph;
• link milestone/issues into this plan and change its status to Active.

Characterization must include:

• spatial and planar raw return combinations;
• diagnostics and normalization combinations;
• external-ID and output-order behavior;
• standard-mode include_empty behavior and power-mode empty/hidden cells;
• current powerfit imports, public types, records, and report fields;
• paper/notebook calls that must remain reproducible under the compatibility route.

Acceptance criteria:

• the plan is Active and linked to the milestone;
• required compatibility behavior is testable;
• the API inventory reflects actual v0.6.3 behavior, including inconvenient behavior;
• dependent issues have clear scope and acceptance criteria.

WP-02 — Neutral weight transforms and weight-first forward API

Purpose: let users compute the mathematical power diagram without manually choosing a Voro++ radius representation.

Status: Completed by #7, #21, and #8. Neutral ownership, finite-result hardening, and direct spatial/planar weight input were reviewed and accepted before release qualification.

Deliverables:

• move weight/radius conversion implementation to a neutral internal module;
• keep public top-level weights_to_radii and radii_to_weights helpers;
• add direct weights= input to spatial and planar power computation;
• retain radii= for power computation;
• require exactly one of weights= and radii= in power mode;
• reject any supplied weights= or radii= argument in standard mode;
• use one global representation shift and never a componentwise shift;
• expose mathematical weights, backend radii, and representation shift to the structured result contract;
• document units and gauge invariance.

Validation:

• weight and radius calls agree after a known global shift;
• adding a constant to all weights leaves cells, measures, adjacency, and periodic image labels unchanged within justified tolerance;
• conflicting inputs fail clearly;
• standard-mode weighted arguments fail clearly before native computation;
• non-finite input, empty input, and extreme-weight behavior are deterministic;
• 2D/3D and bounded/periodic cases are covered.

Acceptance criteria:

• forward power computation from weights does not import separator code;
• existing valid radius-based power computations remain numerically unchanged;
• representation metadata is available to TessellationResult;
• docs and lifecycle inventory describe the new semantics.

WP-03 — Common TessellationResult and output migration

Purpose: provide one clear forward result in both dimensions without hiding backend capability differences.

Deliverables:

• add pyvoro2.TessellationResult in a forward/common module;
• return it by default from both compute functions;
• add output='result'|'cells', with result as default;
• preserve historical raw list/tuple behavior through output='cells';
• treat planar return_result= and PlanarComputeResult as compatibility-only;
• align site coordinates, external IDs, cell measures, and empty masks with original input order;
• include mode, domain, diagnostics, and power representation metadata;
• provide explicit access/capability behavior for boundaries, periodic image labels, and normalized output;
• avoid computing unrequested expensive geometry solely to fill result fields.

Pragmatic immutability target:

• prefer a frozen, slotted result container;
• make owned aligned arrays read-only when this requires no surprising copy;
• do not recursively freeze or copy raw cell dictionaries;
• document contained mutability;
• defer deeper immutability if it complicates construction, extension, or performance.

Compatibility details to resolve inside the issue:

• exact interaction of output='cells' with return_diagnostics;
• warning behavior for planar return_result=;
• whether any rarely used tuple combination needs a narrow wrapper;
• exact stable versus provisional field list in the API inventory.

These are implementation details within ADR 0005, not permission to change its core decisions.

Validation matrix:

• 2D and 3D;
• bounded and periodic domains;
• standard and power modes;
• preferred and raw output;
• external IDs;
• diagnostics on/off;
• normalization where currently supported;
• empty cells;
• boundary records and periodic shifts where requested;
• no incidental mutation of input arrays.

Acceptance criteria:

• a downstream caller uses one documented result type in both dimensions;
• raw output behavior is explicitly available and tested;
• old planar result imports migrate through an alias;
• optional data availability is honest;
• no list-like emulation or deep-immutability machinery obscures the API.

WP-04 — Canonical inverse implementation ownership

Purpose: make pyvoro2.inverse.separator the real implementation home.

Deliverables:

• create pyvoro2.inverse and pyvoro2.inverse.separator;
• move separator implementation modules under the canonical package;
• update internal imports and tests to use canonical ownership;
• keep weight transforms in the neutral forward/shared location from WP-02;
• replace pyvoro2.powerfit modules with narrow import/delegation shims;
• ensure canonical code never imports from pyvoro2.powerfit;
• update packaging and lazy-import behavior.

Acceptance criteria:

• all numerical implementation is owned by the canonical namespace;
• compatibility modules contain no duplicated formulas or solver paths;
• the full existing separator test suite passes through canonical imports;
• package/build/distribution checks include the new namespace;
• import dependency direction is testable or easily auditable.

WP-05 — Canonical separator names and compatibility shims

Purpose: give new users a concise mathematical API while providing one bounded migration release.

Deliverables:

• implement preferred core names from ADR 0004;
• define the exact old-to-new name map in the API inventory;
• expose the small high-level surface from pyvoro2.inverse;
• expose advanced objects from pyvoro2.inverse.separator;
• classify active-set functionality as experimental;
• keep pyvoro2.powerfit and broad top-level separator exports compatibility-only for v0.7;
• add hidden-by-default DeprecationWarning behavior where clean and non-disruptive;
• document the fixed v0.8 removal.

Compatibility aliases should preserve semantic behavior and useful isinstance relationships where practical. They do not need to preserve every repr, module path, or pickling detail unless WP-01 identifies a real public requirement.

Acceptance criteria:

• new-user examples use only pyvoro2.inverse or pyvoro2.inverse.separator;
• historical documented imports still work in v0.7;
• canonical and compatibility paths produce equivalent numerical results;
• __all__, reference pages, warnings, and API inventory agree;
• the compatibility layer has a clear removal horizon.

WP-06 — Separator result layering and algebraic operator access

Purpose: make the mathematical structure inspectable and prepare vocabulary that later observation families can reuse.

Status: Completed by #13 and #14. Issue #13 added the layered result views; issue #14 added problem-owned observation-graph and quadratic-operator views with dense NumPy and optional lazy SciPy conversion.

Deliverables:

• map current fit/problem/realization/active-set results onto distinct views:
• fitted state and identification metadata;
• objective contributions;
• observation targets, predictions, residuals, and confidence;
• algebraic graph/operator diagnostics;
• realized geometry and requested-image matching;
• solver and active-set path diagnostics;
• expose oriented observation endpoints, implied edge-difference targets, edge weights, connected components, normal-system right-hand side, and Laplacian/operator metadata;
• provide dense NumPy conversion and optional SciPy conversion without making a SciPy matrix the only public representation;
• use explicit global-gauge and component-offset terminology;
• preserve JSON-friendly records and reports;
• avoid duplicating large arrays merely to present layered views.

Acceptance criteria:

• users can inspect the effective graph and quadratic operator without private solver imports;
• diagnostics reproduce current predictions and normal equations;
• zero-confidence and disconnected cases are correct;
• periodic parallel observations remain distinct rows;
• hard-infeasibility witnesses and report serialization remain intact;
• active-set results remain clearly experimental and separate from the exact fixed-observation fit.

WP-07 — Paper-style and chemvoro-shaped integration validation

Purpose: test the preferred API as a downstream scientific package would use it before final lifecycle classification, after WP-09 records and validates the static sparse-execution path.

Deliverables:

• add a chemistry-neutral workflow shaped like chemvoro: external IDs, downstream metadata, separator observations, weight fitting, forward realization from weights, result access, and record/report export;
• include a compact paper-style regression subset covering: exact recovery, disconnected observations, hard infeasibility, periodic image handling, realization mismatch, and active-set diagnostics;
• store the selected cases as public, deterministic, repository-owned assets rather than only behavior dispersed across unrelated unit tests;
• provide one canonical preferred-API inverse workflow suitable for guide and notebook reuse, including periodic separator/image behavior;
• cover dense/sparse numerical agreement and inspectable backend selection from WP-09;
• verify that the workflow does not import private modules, infer arbitrary radius shifts, depend on raw record order, or use compatibility-only paths;
• record awkward APIs as focused follow-up fixes before lifecycle finalization.

Acceptance criteria:

• the workflow uses only preferred documented APIs;
• IDs survive forward and inverse round trips;
• gauge/component-offset metadata is sufficient for interpretation;
• cells, measures, boundaries, shifts, and reports are accessible without implementation knowledge;
• the public regression assets are reproducible from repository-owned inputs;
• the canonical workflow is suitable for user-facing documentation and periodic examples;
• the WP-09 static sparse execution path is reflected in the tested execution paths;
• paper-style behavior remains unchanged within justified tolerance.

WP-07A — Reproducible notebook execution and published outputs

Purpose: publish notebook results produced with real Jupyter semantics without making documentation builds execute native code or introducing notebook packages as runtime dependencies.

Deliverables:

• add notebook-only development dependencies based on nbformat, nbclient, and ipykernel;
• add a reproducible execution tool that clears, executes, and saves source notebooks in a clean Jupyter kernel;
• replace plain-Python exec(...) validation with notebook-semantic execution;
• require execution counts for committed executable cells unless an explicit skip-execution tag applies;
• keep Markdown export non-executing and deterministic;
• define a narrow policy that prevents meaningless churn from rich or nondeterministic output, especially py3Dmol output;
• after WP-07 migrates examples to the preferred v0.7 API, execute notebooks 04, 06, 07, and 08 and regenerate their Markdown pages;
• document execution, validation, and export as separate maintenance steps.

Repository commands for this work package are, respectively, python tools/execute_notebooks.py, python tools/check_notebooks.py, and python tools/export_notebooks.py. Checking and export are non-mutating and non-executing, respectively; ordinary MkDocs builds consume committed pages.

Acceptance criteria:

• stored print and final-expression outputs appear in the generated pages;
• notebook validation uses a real Jupyter kernel and reports execution errors with useful cell context;
• unexecuted cells fail metadata validation unless explicitly skipped;
• ordinary MkDocs builds and Markdown export do not execute notebook code;
• notebook dependencies remain outside pyvoro2 runtime requirements;
• clean execution and routine refreshes avoid unnecessary rich-output diffs.

WP-08 — Lifecycle inventory, migration, and documentation finalization

Purpose: turn the implemented code into an explicit public contract.

Status: Completed by #16. The final inventory, migration documentation, generated files, strict documentation build, clean source build, and release-environment checks were verified during issue #18 qualification and approved by the maintainer on 2026-07-23.

Deliverables:

• finalize docs/development/api-inventory.md;
• publish exact stable, provisional, experimental, compatibility-only, and internal classifications;
• add a v0.6.3-to-v0.7 migration guide;
• add an explicit API-choice guide distinguishing high-level pyvoro2.inverse, advanced pyvoro2.inverse.separator, and compatibility-only pyvoro2.powerfit;
• publish a concise feature/lifecycle status table;
• explain the layered result vocabulary schematically and consolidate a glossary for weights, radii, representation shifts, gauge/component offsets, separator observations, realized faces, and active sets;
• verify the documented editable-install/bootstrap path for native source builds;
• update architecture, guides, reference, notebooks, examples, and __all__;
• document the structured default and output='cells' migration;
• document canonical separator names and v0.8 removal horizon;
• state mutability of the result object and contained raw records honestly;
• update changelog and release notes continuously.

Acceptance criteria:

• every documented public surface has a lifecycle status;
• a new user can find one preferred forward and inverse path;
• high-level, advanced, and compatibility inverse routes are distinguished explicitly;
• feature status, result layers, and core terminology are understandable without reading implementation modules;
• a v0.6.3 user can migrate without reading source code;
• README, guides, reference, notebooks, inventory, and implementation agree;
• the maintainer approves the inventory before release qualification.

WP-09 — Sparse quadratic separator solving for large static geometries

Purpose: make large static separator-fitting problems practical while preserving the simple dense path for small problems.

Status: Completed by #17.

The sparse implementation is required before WP-07. It is limited to the primary quadratic separator workflow and does not extend the v0.7 scope to trajectory-scale processing or parallel tessellation.

Deliverables:

• implement sparse incidence and weighted Laplacian assembly;
• add optional SciPy-backed sparse direct solving;
• preserve dense fallback for small problems and installations without SciPy;
• validate componentwise gauge handling;
• expose backend selection and solver metadata;
• compare dense and sparse numerical results;
• benchmark representative static observation graphs.

Benchmark cases:

• small dense-favorable cases;
• medium and large sparse static graphs;
• molecular-shaped locality graphs;
• connected and disconnected components;
• periodic parallel observations where relevant.

Measure:

• assembly time;
• solve time;
• memory usage;
• numerical agreement;
• practical scaling regime.

Out of scope:

• trajectory/frame-sequence APIs;
• warm starts between changing geometries;
• reusable prepared solvers across MD frames;
• parallel forward tessellation;
• GPU/distributed execution;
• scalable all-pairs observation graphs.

A later post-1.0 design issue tracks dynamic and parallel workflows separately.

WP-10 — Release qualification and plan completion

Purpose: verify the whole release contract and close the plan honestly.

Status: Completed for the final v0.7.0 release source during issue #18 review. The separate release checklist remains the operational record for release-commit CI, the tag, tagged artifacts, PyPI publication, and post-publication verification. A failed operational gate requires correction before publication and does not become an unexplained exception.

Deliverables:

• resolve or defer every milestone issue;
• approve the final API inventory;
• maintain and execute an explicit version-controlled release checklist;
• record release-qualification evidence in the v0.7.0 release checklist;
• run deterministic tests, relevant fuzz/cross-check groups, notebook checks, clean Jupyter execution, strict docs, distribution builds, and release tooling;
• test clean installation from built artifacts on supported Python versions;
• audit current-versus-target wording and migration behavior;
• finalize [0.7.0] - 2026-07-23, release notes, and release metadata;
• add an outcome summary and include the archived plan in the final release source.

GitHub milestone and implementation issues

The operational progress view is the v0.7.0 — Forward and separator API stabilization milestone. This section is the maintained, version-controlled source of truth for its issue sequence and dependencies; the table is authoritative.

Planning authority is divided deliberately:

• accepted ADRs define durable architectural decisions;
• this plan defines release scope, work packages, dependencies, and release gates;
• GitHub issue bodies define detailed implementation contracts and acceptance criteria;
• the GitHub milestone provides the operational progress view; and
• issue and pull-request comments are discussion and historical records, not maintained planning authority.

The initial milestone-map comment in #6 is historical. If it differs from this repository plan, this plan supersedes it. Do not edit or delete the historical comment solely to synchronize the map.

The main sequence has two implementation branches after #6:

• forward issues #7 and #21 are complete; the forward-input branch now proceeds through #8, while #9 starts from #6 and coordinates with #8; #8 and #9 converge at #10;
• inverse ownership and API work proceeds through #11, #12, #13, and #14; and
• after #14, issue #17 implements and benchmarks the optional sparse static quadratic path;
• the required branches then converge at #15, followed by #20, #16, and release qualification in #18.

Issue #17 is the required sparse static implementation gate before #15 and is complete. The dependency table below is authoritative where several branches converge.

Issue	Outcome	Dependencies	Classification
#6	Activate the plan and characterize the v0.6.3 public baseline.	None	Required
#7	Move weight/radius transforms to neutral ownership.	#6	Required
#21	Reject non-finite and overflowing weight/radius transform results.	#7	Required correctness prerequisite
#8	Add direct weight-first forward computation in 2D and 3D.	#21	Required
#9	Implement the common TessellationResult data contract.	#6; coordinate with #8	Required
#10	Make structured forward results the default and preserve raw output explicitly.	#8, #9	Required
#11	Move separator implementation ownership to pyvoro2.inverse.separator.	#6, #7	Required
#12	Add canonical separator names and bounded v0.7 compatibility shims.	#11	Required
#13	Introduce layered separator result and diagnostic views.	#11, #12	Required
#14	Expose graph, incidence, and quadratic operator views.	#13	Required
#17	Implement and benchmark dense/optional-sparse quadratic separator solving for large static geometries.	#14	Required
#15	Add paper-style regressions and a chemvoro-shaped integration workflow.	#8, #10, #12, #13, #14, #17	Required
#20	Execute example notebooks and publish their outputs reproducibly.	#15	Required
#16	Finalize the v0.7 API inventory, migration guide, and documentation.	#20	Required
#18	Qualify and release v0.7.0.	All required milestone work	Release

One follow-up remains outside the required release chain: #19 — Integrate finalized manuscript figures and references into the theory documentation. Issue #19 is unmilestoned and does not block v0.7.

Issue contract for coding-agent implementation

Each implementation issue should be self-contained enough that a fresh coding agent can work without private chat history. Include:

• the user/scientific outcome;
• the relevant work package and ADR links;
• in-scope and out-of-scope behavior;
• current baseline behavior that must be characterized or preserved;
• required public names/defaults where already decided;
• acceptance criteria expressed as observable behavior;
• required tests and documentation;
• suggested validation commands;
• dependencies and explicit stop conditions.

Do not prescribe line-by-line implementation when several clean internal solutions satisfy the accepted contract. The agent may refactor local internals as needed, provided scope, architecture, numerical semantics, tests, and compatibility requirements are preserved.

An implementation chain should stop and request maintainer input when it finds:

• a required public behavior that conflicts with an accepted ADR;
• a need for a new mandatory dependency;
• a material numerical difference from the characterized baseline;
• an unplanned breaking change beyond the documented migration;
• a scope expansion into a non-goal;
• a result/namespace choice not covered by the plan or inventory.

At completion, the agent should report:

1. files and public behavior changed;
2. compatibility and lifecycle impact;
3. tests and validation commands run;
4. any deviations, deferred items, or follow-up issues.

This handoff format is guidance, not a requirement to generate unnecessary process documents inside the codebase.

Dependency and parallelism guidance

Recommended order:

1. WP-01 first.
2. Neutral transforms in WP-02 before moving separator modules; complete #21 numerical hardening before direct weight-first computation.
3. Weight-first computation and the core result class may proceed in separate issue branches after characterization, but their metadata contract must be coordinated.
4. Move implementation ownership before adding the full canonical name map.
5. Result/operator layering follows canonical namespace ownership.
6. Run WP-09 after the operator view exists and qualify the narrow static sparse path before downstream validation.
7. Begin downstream validation after WP-09; use findings to refine provisional conveniences and test dense/sparse behavior.
8. After downstream validation and notebook API migration, execute and publish notebook outputs through WP-07A.
9. Finalize lifecycle and migration documentation after WP-07A.
10. Release qualification is last and requires WP-07A and WP-08.

Avoid one giant namespace/result/solver commit. Small dependent changes make regression isolation and final review much easier.

Compatibility and migration contract

v0.7 intentionally changes the preferred API while retaining explicit migration routes:

• radii= remains supported;
• weights= becomes a first-class forward input;
• compute(...) returns TessellationResult by default;
• output='cells' preserves raw list/tuple behavior;
• planar return_result= and PlanarComputeResult are compatibility-only;
• pyvoro2.inverse is preferred;
• pyvoro2.powerfit and broad top-level separator exports remain compatibility-only for v0.7;
• canonical implementation lives only under pyvoro2.inverse.separator;
• historical inverse and planar transition paths are removed in v0.8 under ADR 0006;
• current scientific meanings, record keys on the explicit raw route, and paper archive behavior are preserved unless a separately approved correction is required.

Pre-1.0 status permits these deliberate changes. The release must make them obvious through warnings where appropriate, migration examples, and release notes.

Validation strategy

Forward matrix

Dimension	Domain	Mode	Output	Additional checks
2D	Box	Standard / power	Result / cells	IDs, measures, diagnostics, normalization
2D	Rectangular periodic	Standard / power	Result / cells	Edge shifts, reciprocity, wrapping
3D	Box	Standard / power	Result / cells	IDs, volumes, faces, empty cells
3D	Orthorhombic periodic	Standard / power	Result / cells	Partial periodicity and face shifts
3D	Triclinic periodic	Standard / power	Result / cells	Image labels, remapping, robustness

Required cross-cutting checks:

• weights/radii equivalence;
• global-shift invariance;
• conflicting input errors;
• aligned IDs, measures, and empty masks;
• optional data absence and require_* behavior;
• documented contained mutability;
• preferred versus raw output equivalence;
• no eager costly geometry solely for result completeness.

Separator inverse matrix

• exact connected recovery modulo global gauge;
• disconnected components and explicit offset policy;
• zero-confidence rows and effective-graph semantics;
• squared and Huber fits;
• infeasible equality/interval restrictions with witnesses;
• repeated and periodic parallel observations;
• requested image versus realized other image;
• algebraic fit without realized boundary support;
• active-set termination, cycling, and path diagnostics;
• canonical versus compatibility imports and name aliases.

Downstream and packaging

• chemistry-neutral chemvoro-shaped integration;
• public deterministic paper-style regression assets and a canonical inverse workflow suitable for guide/notebook reuse;
• clean wheel and source-distribution installation;
• generated README/notebook synchronization;
• notebook execution in a clean Jupyter kernel with execution-count and explicit-skip validation;
• stored print and final-expression outputs rendered by deterministic, non-executing Markdown export;
• narrow rich-output handling that avoids routine py3Dmol churn;
• notebook execution dependencies confined to development/documentation extras;
• strict documentation build;
• full release check;
• supported Python CI and wheels;
• canonical inverse modules included in distributions;
• compatibility modules excluded from architecture ownership but included for the transition release.

Documentation outputs

Required artifacts:

• ADR 0004, ADR 0005, and ADR 0006;
• finalized and maintainer-approved v0.7 API inventory;
• updated current/target architecture;
• preferred forward and separator guides;
• exact reference pages for TessellationResult and pyvoro2.inverse;
• v0.6.3-to-v0.7 migration guide and explicit API-choice/glossary pages;
• explicit API-choice guidance, feature/lifecycle status, result-layer explanation, and core inverse glossary;
• chemvoro-shaped integration example or note;
• executed source notebooks and generated pages containing their reviewed textual outputs;
• release notes and changelog;
• an explicit version-controlled release checklist;
• completed outcome section in this plan.

The finalized-manuscript figures/references issue remains separate and non-blocking.

Final release-source acceptance and operational gates

The archived plan is part of the final v0.7.0 source so the tagged version contains its own outcome and development history. Plan completion does not stand in for external release operations: release-commit CI, tagged artifact validation, PyPI publication, and public smoke checks remain explicit gates in the v0.7.0 release checklist. If any such gate fails, the release source must be corrected before publication.

Completed repository and maintainer gates

• [x] The v0.6.3 public baseline is inventoried and characterized.
• [x] Neutral weight transforms and direct weight-first computation exist in 2D and 3D.
• [x] TessellationResult is the preferred/default result in both dimensions.
• [x] The explicit raw-output route is tested.
• [x] Core result IDs, measures, empty state, diagnostics, and representation metadata are documented and aligned.
• [x] Canonical separator implementation is owned by pyvoro2.inverse.separator.
• [x] Preferred separator names and high-level imports are implemented.
• [x] pyvoro2.powerfit, top-level inverse exports, historical aliases, and planar transition paths work for v0.7 and have a fixed v0.8 removal horizon.
• [x] Algebraic, identification, realization, and solver diagnostics are inspectable and clearly distinguished.
• [x] The API lifecycle inventory is complete and maintainer-approved on 2026-07-23.
• [x] Issue #17 is closed with the static sparse implementation included.
• [x] The chemvoro-shaped workflow passes using preferred public APIs only.
• [x] Public deterministic paper-style regression assets pass without unexplained numerical changes.
• [x] Included sparse execution is covered by integration regressions and benchmark assets.
• [x] Source notebooks are committed in an executed state, except for explicitly skipped cells, and validate with real Jupyter semantics.
• [x] Stored notebook print and final-expression outputs appear in the generated pages without unnecessary rich-output churn.
• [x] API-choice guidance, feature status, result-layer explanation, glossary, migration documentation, and release notes are complete.
• [x] Full local tests, fuzz checks, strict docs, packaging, clean-install, and sparse/no-SciPy qualification pass with recorded evidence.
• [x] README and notebook exports are synchronized.
• [x] Required implementation and documentation issues #6–#17, #20, and #21 are closed; #19 and #23 are explicitly nonblocking.
• [x] The changelog is finalized as [0.7.0] - 2026-07-23.
• [x] Independent review and maintainer approval accept the final inventory, release-source corrections, and tag-and-PyPI-only publication model.

Remaining operational gates

• [ ] The final release commit passes supported Linux, macOS, and Windows CI on Python 3.10–3.13, including lint/generated-file, docs/notebook, and distribution jobs.
• [ ] The reviewed dev state is integrated into main and the annotated or signed v0.7.0 tag is pushed.
• [ ] Tagged wheel/sdist artifacts are collected and independently validated.
• [ ] v0.7.0 is published to PyPI and passes a clean public-install smoke test.
• [ ] Published metadata, hashes, and deployed documentation are verified; issue #18 and the v0.7 milestone are then closed.
• [x] By explicit maintainer decision, v0.7.0 has no GitHub Release or Zenodo archive. The next full GitHub/Zenodo archival release is planned for v0.8.0.

Risks and mitigations

Risk	Consequence	Mitigation
The common result grows into a large eager object.	Forward calls become slower and harder to understand.	Keep optional data absent, preserve raw records, and avoid unrequested geometry.
Deep immutability becomes an implementation project of its own.	API stabilization is delayed for little user benefit.	Freeze the outer structure where clean; document raw contained mutability and defer deeper work.
Changing the default return surprises users.	Existing code receives a different type.	Provide output='cells', migration examples, compatibility tests, and clear release notes.
Moving modules causes circular imports or duplicated logic.	Canonical and compatibility behavior diverge.	Move neutral transforms first; enforce one-way shim dependencies and test both paths.
Renaming too many secondary objects creates noise.	Migration cost exceeds clarity benefit.	Stabilize a small high-level canonical surface; keep advanced names provisional and map them deliberately.
Top-level compatibility exports linger indefinitely.	Namespace remains cluttered.	Publish the v0.8 removal horizon in ADR, inventory, warnings, and release notes.
One result class hides real 2D/3D differences.	Users infer unavailable capabilities.	Use optional fields/capability checks and explicit dimension-specific raw geometry.
Lifecycle labels are assigned too early.	v0.7 promises more than evidence supports.	Maintain the inventory continuously and use provisional status where uncertain.
A coding agent expands issue scope.	Review and regression isolation become difficult.	Use self-contained issues, explicit non-goals and stop conditions, and one issue per implementation chain.
Notebook execution or rich output is nondeterministic.	Routine refreshes create large meaningless diffs or documentation becomes irreproducible.	Execute only through the dedicated Jupyter workflow, keep export non-executing, allow explicit skip tags, and define narrow handling for py3Dmol output.
Notebook packages leak into runtime requirements.	Minimal pyvoro2 installation becomes heavier for unrelated users.	Keep nbformat, nbclient, and ipykernel in notebook-only development extras and never execute notebooks during MkDocs builds.
Sparse support becomes a mandatory dependency.	Minimal installation and packaging become harder.	Keep SciPy optional, retain dense execution, and reject unsupported branches explicitly.

Plan revisions

Date	Revision	Change	Reason
2026-07-17	0.1	Initial draft	Establish release-specific planning after the architecture and development-policy documentation was added.
2026-07-17	0.2	Accept canonical inverse and common-result decisions; add API inventory, bounded compatibility schedule, pragmatic immutability, and implementation-agent handoff guidance	Maintainer review of D-07-1 through D-07-4.
2026-07-18	0.3	Activate the plan and link the v0.7 milestone and issue sequence	The milestone and issues #6–#18 were created after scope and architecture approval.
2026-07-18	0.4	Add required reproducible notebook execution and published-output work after downstream validation and before documentation finalization	Issue #20 formalized notebook execution, stored-output, dependency, and rich-output policy and blocks issues #16 and #18.
2026-07-18	0.5	Complete WP-01 baseline characterization and link its executable compatibility tests to the API inventory	Issue #6 recorded the exact v0.6.3 forward/inverse exports, return variants, schemas, defaults, and example-call dependencies before implementation issues begin.
2026-07-18	0.6	Make the repository plan authoritative for the v0.7 milestone issue map and dependencies	Preserve the maintained sequence, including required notebook issue #20 and conditional issue #17, independently of historical issue comments.
2026-07-18	0.7	Complete the WP-01 follow-up audit of documented module routes, visualization exports, notebook calls, and ADR reconciliation	Ensure that compatibility characterization covers reference-documented submodules and every callable path used by the source notebooks before dependent implementation begins.
2026-07-18	0.8	Add explicit standard-mode include_empty characterization in both dimensions	The issue scope names standard and power-mode empty-cell behavior separately; the original focused test covered only hidden cells in power mode.
2026-07-19	0.9	Insert issue #21 between neutral transform ownership and direct weight-first forward computation	Non-finite and overflowing transform results are a correctness defect inherited from v0.6.3 and must be rejected before issue #8 consumes the shared transforms.
2026-07-20	1.0	Record completion of the WP-06 result-layering portion while retaining graph/operator access under issue #14	Issue #13 adds non-copying semantic views without pre-empting the representation decisions assigned to issue #14.
2026-07-21	1.1	Complete WP-06 with problem-owned observation-graph and quadratic-operator views	Issue #14 exposes backend-neutral row data, incidence, Laplacian, right-hand sides, matrix-free products, nullspace metadata, and optional lazy SciPy conversions without changing solver execution.
2026-07-21	1.2	Make #17 an include-or-defer decision gate before #15 and fold the post-#14 review into existing validation, documentation, and release issues	The benchmark, API-guidance, notebook, and release findings are already owned by #15, #16, #20, and #18; new omnibus issues would duplicate the maintained issue graph.
2026-07-22	1.3	Finalize the v0.7 lifecycle inventory and documentation; accept v0.8 as a cleanup-only compatibility-removal release and move prescribed measures/mixed fitting to v0.9/v0.10	Maintainer approval of issue #16 classifications and ADR 0006; non-critical audit findings are deferred rather than mixed into v0.7.
2026-07-23	1.4	Finalize and archive the v0.7 release source, reapprove the amended inventory, split repository-plan completion from external publication checks, and adopt a tag-and-PyPI-only v0.7 release model	The final tagged source should contain its completed plan; GitHub Release and Zenodo archival are intentionally reserved for v0.8 rather than created retroactively for the transition release.

Outcome

The final v0.7.0 release source was completed on 2026-07-23 under issue #18. Its approved publication model is an annotated or signed v0.7.0 tag plus PyPI distribution. No GitHub Release or Zenodo version record is created for this transition release; v0.8.0 is intended to be the next full package, GitHub, and Zenodo archival release.

v0.7.0 delivers the common dimension-neutral TessellationResult, direct weight-first forward power computation, canonical separator ownership and math-aligned names under pyvoro2.inverse, bounded v0.7 compatibility routes, layered scientific diagnostics, and inspectable graph/incidence/quadratic operators. The optional SciPy sparse path is included for static unconstrained quadratic separator fitting, agrees with the dense path where both are practical, remains absent from ordinary no-SciPy installations, and avoids a dense global normal matrix in the recorded 4,096-site large case.

Local qualification covered the deterministic suite, lint, notebooks and stored outputs, strict documentation, fuzz checks, examples, paper-style regressions, static benchmarks, source/wheel builds, distribution inspection, and clean wheel installs with and without SciPy. The API inventory, including the stable pyvoro2.result module route and provisional direct construction, was reapproved by the maintainer on 2026-07-23.

The compatibility horizon remains fixed: pyvoro2.powerfit, broad top-level separator exports, historical separator aliases, PlanarComputeResult, and planar return_result= are v0.7 transition routes removed by the feature-free v0.8 cleanup release. Prescribed cell measures begin in v0.9 and mixed separator-plus-measure fitting in v0.10.

Deferred work remains explicit. Final manuscript figures and references stay in unmilestoned issue #19; trajectory-scale and parallel workflows stay in post-1.0 issue #23. The scikit-build-core metadata warning, release-tool shell-glob portability, and other noncritical audit findings move to the v0.8 cleanup plan. Optional pyvoro comparison was unavailable in the CPython 3.13 qualification environment and was not reported as passed.

This archive records the completed repository plan. Supported release-commit CI, tagged artifact validation, PyPI publication, deployed-documentation checks, and final closure of issue #18 and the milestone remain visible in the release checklist; the archive does not silently imply that unchecked external operations have passed.