V0.10 Scope Freeze#

Summary#

v0.10 is the supportability and v1.0 readiness release for pdelie.

Its purpose is:

harden the existing Heat/Burgers/weak-report/KdV engine into a more supportable public surface before adding more numerical scope.

Stable release definition:

existing stable Heat/Burgers/weak-report/KdV surfaces -> compact supportability reports -> consistent examples/release gates/docs -> v1.0 readiness

v0.10 is not a new numerics release. It does not add another PDE, weak KdV, broad adapters, multidimensional grids, or operator-facing work.

Stable Scope#

Stable v0.10 scope is limited to supportability work around the surfaces already stable through v0.9:

  • canonical Heat/Burgers strong paths

  • window-indexed weak Heat/Burgers report APIs

  • structured from_numpy(...) and from_xarray(...) ingestion

  • normalized periodic short-horizon KdV strong path

  • polynomial translation fitting and held-out verification

  • existing examples and release gates

  • package, publishing, and release-readiness documentation

Committed supportability directions:

  • compact runtime reporting helpers over existing residual, fit, verification, and vertical-slice outputs

  • consistent example summaries where useful

  • API stability audit and accidental-public-surface guards

  • CI release-gate cleanup

  • package/readiness documentation cleanup for eventual v1.0 publishing decisions

Public API Policy#

M1 freezes a new runtime-level public helper surface for M2:

  • pdelie.reporting

This is a public runtime submodule. It is not a canonical object system. It has no root pdelie exports.

Frozen M2 public APIs:

summarize_residual_batch(residual: ResidualBatch) -> dict[str, Any]
summarize_weak_residual_report(report: Mapping[str, Any]) -> dict[str, Any]
summarize_generator_family(generator: GeneratorFamily) -> dict[str, Any]
summarize_verification_report(report: VerificationReport) -> dict[str, Any]
summarize_vertical_slice(
    *,
    derivatives: DerivativeBatch,
    residual: ResidualBatch,
    generator: GeneratorFamily,
    verification: VerificationReport,
    extra_metrics: Mapping[str, Any] | None = None,
) -> dict[str, Any]

Frozen common reporting rules:

  • runtime-level, not a canonical object

  • deterministic for identical inputs

  • JSON-compatible plain Python dict outputs

  • NumPy arrays become lists

  • NumPy scalar values become Python scalar values

  • input object types and required report keys are validated

  • validation failures use existing typed validation errors

  • scoped to existing stable surfaces

  • no helper mutates its inputs

  • no helper creates or changes canonical objects

  • no manuscript-specific table, figure, threshold, or label logic

  • no root pdelie exports

  • API_STABILITY.md is updated in M2 when these APIs land

Reporting Helper Schemas#

Every reporting helper returns a dict containing:

  • summary_schema_version = "0.1"

  • summary_type

ResidualBatch Summary#

summarize_residual_batch(...) freezes these keys:

  • summary_schema_version

  • summary_type = "residual_batch"

  • residual_shape

  • definition_type

  • normalization

  • max_abs_residual

  • rms_residual

  • diagnostics

max_abs_residual and rms_residual are computed from residual.residual. The original diagnostics are preserved after JSON-safe conversion.

Weak Residual Report Summary#

summarize_weak_residual_report(...) freezes these keys:

  • summary_schema_version

  • summary_type = "weak_residual_report"

  • equation

  • equation_form

  • method_family

  • normalization

  • window_residual_shape

  • max_abs_residual

  • l2_residual

  • diagnostics

The helper supports the frozen v0.8 weak report shape only. It validates that the input mapping contains the frozen weak report keys before summarizing.

GeneratorFamily Summary#

summarize_generator_family(...) freezes these keys:

  • summary_schema_version

  • summary_type = "generator_family"

  • parameterization

  • normalization

  • coefficient_shape

  • coefficients

  • generator_names

  • translation_span_distance

  • fit_mode

  • reference_fallback_used

  • fallback_reason

  • diagnostics

translation_span_distance is populated only for polynomial_translation_affine. For other parameterizations, it is None. Fit and fallback fields are read from diagnostics when present and otherwise reported as None.

VerificationReport Summary#

summarize_verification_report(...) freezes these keys:

  • summary_schema_version

  • summary_type = "verification_report"

  • norm

  • classification

  • epsilon_values

  • error_curve

  • first_epsilon

  • first_error

  • max_error

  • diagnostics

first_epsilon and first_error are the first entries of the verification sweep. max_error is computed from error_curve.

Vertical Slice Summary#

summarize_vertical_slice(...) freezes these keys:

  • summary_schema_version

  • summary_type = "vertical_slice"

  • derivative_backend

  • derivative_keys

  • derivative_config

  • derivative_diagnostics

  • residual

  • generator

  • verification

  • extra_metrics

The nested residual, generator, and verification values are produced by the corresponding summary helpers. extra_metrics is optional and JSON-safe converted when provided. It must not be used to smuggle manuscript-specific reporting logic into the runtime API.

Reporting helpers must not:

  • redefine canonical object meaning

  • make example outputs canonical artifacts

  • encode manuscript-specific tables or figures

  • hide backend-specific caveats

  • broaden numerical scope

Example Consistency#

Heat and KdV examples should be made more consistent where that improves supportability.

Example outputs remain runtime smoke summaries. They are not stable canonical artifact schemas.

Expected properties:

  • JSON-serializable plain Python values

  • deterministic for frozen example inputs

  • compact enough for command-line smoke checks

  • explicit about backend and verification classification

API Stability Audit#

M0 audits docs/specs/API_STABILITY.md only. M1 freezes future public reporting APIs in planning docs only.

Audit result for M0:

  • all public APIs through v0.9 remain documented

  • no v0.10 public API has landed yet

  • API_STABILITY.md should remain unchanged until reporting helpers or other public APIs actually land

M1 audit result:

  • pdelie.reporting APIs are frozen for M2 but not implemented yet

  • API_STABILITY.md remains unchanged in M1

  • M2 must update API_STABILITY.md when pdelie.reporting lands

Future v0.10 milestones must update API_STABILITY.md in the same milestone where any public API is added or changed.

CI Cleanup Direction#

v0.10 should reduce release-gate CI sprawl without deleting useful historical tests.

Target direction:

  • keep historical release-gate test modules runnable locally

  • keep the current release gate visible in CI

  • avoid redundant historical release-gate CI jobs unless intentionally retained

  • keep full editable tests and package smoke as required release checks

  • do not change test semantics just to make CI faster

Exact workflow edits are deferred until the CI cleanup milestone.

Package and Publishing Readiness#

v0.10 should prepare the project for the v1.0 publishing decision.

Required decision record:

  • whether package-index publishing resumes at v1.0

  • whether v0.10 remains Git-tag-only

  • what local build and wheel-smoke checks are required before any future publishable release

  • what CI jobs are required before tagging

No PyPI or TestPyPI publication is added by this scope freeze.

Scope Limits#

Stable v0.10 scope is limited to:

  • supportability helpers around existing stable runtime surfaces

  • existing canonical objects

  • existing scalar 1D uniform rectilinear / periodic regimes

  • existing Heat, Burgers, weak Heat/Burgers report, and KdV strong-path surfaces

  • documentation and CI release-process cleanup

Explicit Non-goals#

Out of stable v0.10 scope:

  • no new PDE

  • no weak KdV API

  • no new weak derivative API

  • no KdV weak residual report

  • no broad benchmark adapters

  • no PDEBench or The Well adapter work

  • no multidimensional grids

  • no multivariable systems

  • no nonuniform-grid expansion

  • no operator-method expansion

  • no neural generators

  • no manuscript-specific reporting logic

  • no new canonical object unless M1 proves a repeated supportability problem cannot be solved with runtime helpers

Milestones#

Planned v0.10 sequence:

  • Milestone 0 - supportability scope reset

  • Milestone 1 - reporting semantics freeze

  • Milestone 2 - reporting helper implementation

  • Milestone 3 - example consistency

  • Milestone 4 - API stability audit and public-surface guards

  • Milestone 5 - CI cleanup and release-gate consolidation

  • Milestone 6 - release readiness and documentation alignment

API_STABILITY.md is updated only when public APIs land:

  • M0 audits it but leaves it unchanged

  • M1 freezes public reporting contracts in planning docs only

  • M2 updates it when public reporting helpers land

  • later milestones update it only if they add or change public APIs