API compatibility policy

The rebuilt MHX package separates three versioned surfaces:

Surface

Current value

Stability intent

Package version

0.1.0a0

Changes with every release.

Public API version

v1

Compatibility contract for config loaders, plugin interfaces, and artifact readers.

Artifact schemas

mhx.*.v1

File-format contracts for generated outputs.

Claim levels

smoke, validation, production_template, production

Reviewer-facing boundary for what an artifact can support.

Inspect the active values:

mhx api status
mhx api status --json

Reproducibility override

Set MHX_API_VERSION to force loaders and writers to validate the requested public API before doing work:

MHX_API_VERSION=v1 mhx validate all --outdir outputs/validation_suite

Any unsupported value fails early. This is intentionally strict: a reviewer or workflow runner should not silently read an artifact produced under an unrecognized API contract.

TOML configs may also include api_version = "v1". mhx.config.load_config rejects unsupported config API values, and also rejects an unsupported MHX_API_VERSION override even when the config omits the field. Configs without api_version are treated as v1 while v1 is the only supported public API.

Stable v1 interfaces

The following names are part of the rebuilt v1 public surface:

  • mhx.config.RunConfig, MeshConfig, TimeConfig, PhysicsConfig, NumericsConfig, and DiagnosticsConfig.

  • mhx.physics.PhysicsTerm, PhysicsRegistry, PHYSICS_API_VERSION = "mhx.physics.v1", and PHYSICS_ENTRY_POINT_GROUP = "mhx.physics".

  • mhx.diagnostics.DiagnosticSpec, DiagnosticsRegistry, and DIAGNOSTICS_ENTRY_POINT_GROUP = "mhx.diagnostics".

  • mhx.io.read_reduced_mhd_trajectory_npz and mhx.io.write_reduced_mhd_trajectory_npz for mhx.reduced_mhd.trajectory.v1.

  • Manifest claim_level values: unspecified, smoke, validation, production_template, and production.

  • mhx validate all, mhx benchmark ..., mhx figures, mhx report, and mhx artifact-manifest command families.

  • Public CLI families documented for v1: mhx api, mhx campaign, mhx neural-ode, mhx physics, mhx diagnostics, and mhx validate readiness. New subcommands may be added in minor pre-releases; removed or renamed commands require a migration note.

Compatibility rules

  • Patch releases may add optional fields to JSON/NPZ metadata but must keep existing v1 keys readable.

  • Minor pre-releases may add new diagnostics, benchmarks, plugins, and CLI options.

  • Breaking changes require either a new public API version or a documented deprecation window.

  • Active source files must not import archived legacy modules. The CI command python tools/check_legacy_imports.py enforces this.