Migrate to the coordinated pre-v1 API

This delivery combines the HELX alignment work in #136. It is a breaking pre-v1 update, not a product-v1 release. HELX remains independently usable through its CLI and Python API; BENCH is an optional consumer.

Formats and existing results

Artifact	Current format	Migration
Experiment YAML	version 2	Keep existing configurations; review acquisition and tensor options below.
Native result bundle	schema 4	Run the experiment again to create a current bundle.
Frozen plan	format 2	Recreate with freeze; keep required local inputs available.
Retained compiled build	format 2	Recreate with build from a current frozen plan.
Portable result projection	helx-schema4-draft4	Export from a verified current native result using the public API.

Earlier native results, plans and compiled builds are refused by the current reader. There is no archival reader, format-number editing procedure or automatic conversion. Existing files are not deleted. Keep the original producer installation separately if you need to inspect historical captures.

Python and CLI callers

Import public types and operations from helia_estimator.api. Use load_request or EstimateRequest to capture configuration and pass that same request to estimate. Consume EstimateOutcome.result as the verified result; check its execution stage rather than treating any returned bundle as a measured inference.

For reusable executable artifacts, use freeze → build → run_build. Load saved records through load_frozen and load_build. Frozen-plan replay can build normally; retained-build execution reuses the captured executable. Use new output directories for retained builds and replay results.

The Python API guide includes complete Python and CLI examples, public types, filesystem rules and error handling. Offline consumers use inspect_result or load_result, followed by observations or render_result; they should not parse runner logs or reconstruct native facts. An invalid inspection has no verified result. Integrity verification alone does not establish numerical correctness.

Acquisition and numerical evidence

• carry preserves one initialized instance across warmups and measured calls. single permits one measured call with no warmup. Refilling inputs does not reset model state.
• Requested automatic warmup remains null in the portable request. Observed warmup counts are separate facts. Interpreter and AOT initialization boundaries retain their own meanings.
• Acquisition policy is bound into a retained build. Change policy by creating a new build; replay does not silently rebuild it.
• Repeated measurements retain indexed samples and exact counters. Select a sample or an explicit statistic instead of assuming the first sample is an aggregate.
• Tensor capture is opt-in. match, mismatch and not_compared describe numerical assessment separately from execution completion. Missing references do not imply a pass.

See Acquisition lifecycle and Tensor verification for configuration examples.

Consumers of portable results

Keep the source-model digest distinct from transformed runner/model identities. Keep the entire versioned input identity, including its namespace. A HELX input digest is not automatically equivalent to an HPX digest with a matching suffix.

Preserve origins, units, sample counts, memory scopes and unavailable reasons. Configured capacity, interpreter allocator use and AOT static arena storage are different quantities. AOT engine version identifies the captured generating provider; interpreter version identifies the captured linked runtime.

Target identity is available only with a complete retained simulation-configuration receipt. Earlier captures without that evidence remain readable with null identity. BENCH refuses comparisons requiring missing target facts. See simulation target identity. Do not fill missing facts from current dependency pins, filenames, successful execution or output agreement. BENCH owns comparison admission; HELX owns native evidence and its projection.

Viewer workflows remain documented in Parse and visualize results. This cutover retains PMU, modeled energy, fencing, tracing, Model Explorer and Perfetto features.