feat(runner): successive-halving and Hyperband (#104)

[jc-macdonald]

Closes #104.

Summary

Adds multi-fidelity early-stopping of trials within a batch via successive-halving and Hyperband. Distinct from #78 (closed), which proposed phase-level fidelity swap; this prunes trials within a single phase based on intermediate observations.

New API

PartialEvaluator protocol (protocols.py)

@runtime_checkable
class PartialEvaluator(Protocol):
    def evaluate(self, config: dict[str, Any], budget: float) -> dict[str, float]: ...

Budget is opaque to the runner — interpret it as epochs, MCMC iterations, dataset fractions, mesh resolutions, or seconds. Implementations are free to cache intermediate state internally.

run_successive_halving (runner.py)

results = run_successive_halving(
    trials,
    sim,
    rungs=[1, 3, 9, 27],
    eta=3,
    metric="val_loss",
    mode="min",
)

• Evaluates every trial at the lowest rung.
• Keeps top ceil(n_prev / eta) by metric at each rung; promotes survivors.
• Records every (trial, rung) evaluation as one row in ResultsTable.
• Per-row metadata: rung, budget, trial_index, promoted, wall_seconds.

run_hyperband (runner.py)

Implements the Li et al. (2017) bracket schedule on top of successive-halving. Takes a trial_factory(bracket_idx, n) -> trials callable so brackets can sample independently (e.g. with bracket-derived seeds passed to build_grid).

Tests

11 new tests in tests/test_runner.py:

• ranking correctness (lowest target survives)
• row count across rungs
• metadata schema (rung/budget/trial_index/promoted/wall_seconds)
• mode="max" reverses ranking
• input validation (empty trials/rungs, non-ascending, eta ≤ 1, bad mode)
• KeyError on missing metric
• Hyperband bracket coverage
• PartialEvaluator runtime-checkable

CI

just ci clean: lint, mypy strict, 284 tests pass, runner.py at 97% coverage.

Follow-ups

• Regime-conditional surrogate: interpolate factor recommendations across regime features #105 — regime-conditional surrogate (depends on Surrogate modeling: GP/RF interpolation from results table #82)
• ASHA (asynchronous variant) — could be added later as a parallel-execution mode of run_successive_halving.