Module trial 

Trials: state, snapshots, handles and deltas.

A trial is one evaluation of one configuration. Its life is a small state machine — the guide walks it in Studies and trials:

Waiting ──ask──► Running ──tell──► Complete
                   │ ├──report──► (intermediate values, heartbeat)
                   │ ├──scheduler──► Pruned | Paused ──resume──► Running
                   └──panic/err──► Failed { error, retries }

Three rules matter beyond the diagram:

• Finished trials are immutable. Complete, Pruned and Failed are terminal; storage rejects writes to them.
• A pruned trial adopts its last intermediate value as its objective value (FrozenTrial::objective_value). ASHA’s correctness depends on it.
• Failed trials are invisible to samplers but their record, parameters and error text survive. Losing them (as some prior art does) throws away the most interesting data a tuning run produces.

Structs

FrozenTrial

The immutable snapshot of a trial.

TrialDelta

One change to one trial, as seen through Storage::sync.

TrialMeta

The lightweight handle a sampler receives for the trial it is sampling.

TrialRecord

What storage returns when a trial is created.

TrialTemplate

A request to create a trial with something already decided.

Enums

TrialState

Where a trial is in its life cycle.

Functions

require_objective_value

Convenience: the objective values of a completed trial, or an error.