# 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](https://ambiqai.github.io/helia-estimator/guides/python-results/) 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](https://ambiqai.github.io/helia-estimator/guides/acquisition/) and
[Tensor verification](https://ambiqai.github.io/helia-estimator/guides/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](https://ambiqai.github.io/helia-estimator/guides/python-results/#simulation-target-configuration-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](https://ambiqai.github.io/helia-estimator/guides/view-results/). This cutover retains PMU,
modeled energy, fencing, tracing, Model Explorer and Perfetto features.