# `Beaver.MLIR.Transform.Tuner`

Bounded, deterministic BEAM evaluation of resolved Transform schedules.

Candidate order is the order returned by `Schedule.enumerate/2`, independent
of task completion order. Timeouts kill the individual task. Cancellation is
shared through an explicit token and can also be observed by cooperative
evaluator callbacks.

Searches emit `[:beaver, :mlir, :compilation, :autotuning, :start | :stop]`
and each candidate emits the corresponding
`[:beaver, :mlir, :compilation, :autotuning, :candidate, :start | :stop]`
events. Candidate metadata can be passed to `Beaver.MLIR.ActionTracing` to
correlate lower-level MLIR actions with the schedule that caused them.

# `evaluator`

```elixir
@type evaluator() :: function() | module() | {module(), term()}
```

# `search`

```elixir
@spec search(Beaver.MLIR.Transform.Schedule.input(), evaluator(), keyword()) ::
  {:ok, Beaver.MLIR.Transform.Tuner.Result.t()}
  | {:error, Beaver.MLIR.Transform.Error.t()}
```

Resolves and evaluates every candidate with bounded concurrency.

An evaluator may return a bare value, `{:ok, value}`,
`{:ok, value, metadata}`, or `{:error, reason}`. Beaver records these values
without imposing a scoring or winner-selection policy.

# `search!`

```elixir
@spec search!(Beaver.MLIR.Transform.Schedule.input(), evaluator(), keyword()) ::
  Beaver.MLIR.Transform.Tuner.Result.t()
```

Bang variant of `search/3`.

# `select`

```elixir
@spec select(Beaver.MLIR.Transform.Tuner.Result.t(), ([
                                                  Beaver.MLIR.Transform.Tuner.Candidate.t()
                                                ] ->
                                                  term())) :: term()
```

Passes successful records to an application-defined selection function.