feat!: move CMA-ES distribution into CmaEsState (B8)

CMA-ES was the one solver parking its iterate — the search distribution
(m, σ, C, B/D, evolution paths) — on the solver struct, which forced its
canonical TolX test to be a hardcoded `terminate` hook that ignored its
state argument (routing around tenet 3) and contradicted the crate's own
articulated principle that working state lives in the state, not the
solver (see LbfgsState).

Introduce `CmaEsState<V, M, F>` (core/state/cma_es.rs): one shared state
for both CmaEs and BoundedCmaEs, holding the distribution plus the
population, with the bounded variant's adaptive-penalty bookkeeping
riding along as `Option<BoundPenalty>` (mirroring LbfgsState::work). No
bespoke trait — the new `CmaEsTolerance` criterion binds the concrete
state and fires `TerminationReason::CmaEsTolerance`.

Both solvers become configuration-only: `CmaEs::new(seed)` /
`BoundedCmaEs::new(seed)`, with mean/σ/stds on
`CmaEsState::new(mean, σ).with_stds(...)` and the old `with_tol_x`
replaced by the criterion. Derived constants + RNG are cached on the
solver.

Result semantics follow canonical CMA-ES: `param()`/`cost()` return the
distribution mean (xfavorite; the solver evaluates f(m) once per
generation), while `best_param()`/`best_cost()` return the best
evaluated sample (xbest) — an OptimizationResult surfaces both. The
PopulationState contract is relaxed so `param()` need not equal
candidates[0]; MaLsChCma's chain write-back reads best_param().

Updates the injection/chain consumers, lib re-exports, wasm bindings,
benches, the CMA test suite across all backends, and docs (AGENTS.md
observer-KV note, audit B8 marked resolved, solver-composition rule).

Verified: cargo test --workspace --all-features (699 pass), clippy
(all targets/features), doc build, wasm target, web build.

BREAKING CHANGE: CMA-ES public API changed. `CmaEs::new` /
`BoundedCmaEs::new` now take only `(seed)`; the initial mean and σ move
to `CmaEsState::new(mean, sigma)`, and the Executor state for both
solvers is now `CmaEsState<V, M>` instead of `BasicPopulationState<V>`.
`CmaEs::with_stds` / `with_tol_x` are removed — use
`CmaEsState::with_stds(...)` and the `CmaEsTolerance` termination
criterion. `OptimizationResult::param()` / `cost()` now return the
distribution mean (xfavorite), not the best sample; use `best_param()` /
`best_cost()` for the best evaluated point. Standalone CMA-ES no longer
self-terminates on TolX unless a `CmaEsTolerance` criterion is registered.

Author: jolars

.claude/rules/solver-composition.md

@@ -86,10 +86,10 @@ Each shipped state has its own mirror rule:
   `gradient_evals = gradient + jacobian + hessian` (the NLLS convention
   preserved — residual rolls into cost, Jacobian/Hessian into gradient).
 - Derivative-free states (`BasicSimplexState`, `BasicPopulationState`,
-  `MaLsChState`): `cost_evals = total_work()` — every kind of work folded
-  in. This is what makes a CMA-ES outer with an L-BFGS inner just *work*:
-  the inner's gradient evals show up in the outer's `cost_evals` honestly,
-  with no manual cross-type fold.
+  `CmaEsState`, `MaLsChState`): `cost_evals = total_work()` — every kind of
+  work folded in. This is what makes a CMA-ES outer (which drives a
+  `CmaEsState`) with an L-BFGS inner just *work*: the inner's gradient evals
+  show up in the outer's `cost_evals` honestly, with no manual cross-type fold.
 
 User-defined state types plugging into `Executor` must impl `CountsMirror`;
 it is `pub` for exactly that reason.
@@ -107,8 +107,8 @@ inner's state, not just drive it — and inners carry different state shapes
   `seed_scaled(x, σ)` (defaults to `seed`; only Nelder-Mead's σ-scaled simplex
   overrides it). No per-trait eval-aggregation hook — same-problem composition
   shares the `Problem<P>` wrapper, and the `total_work()` fold in
-  `BasicPopulationState`'s `CountsMirror` rolls every kind of inner work into
-  the outer's single `cost_evals` automatically.
+  `CmaEsState`'s `CountsMirror` (same rule as `BasicPopulationState`) rolls
+  every kind of inner work into the outer's single `cost_evals` automatically.
 
 Two consumer families validate the split: the barrier / AL methods bound `So:
 WarmStart<V>` with `So::State: GradientState + CountsMirror` (gradient inners

AGENTS.md

@@ -50,11 +50,13 @@ the relevant files. Don't duplicate it here:
   to it, and existing `Observe` impls keep compiling via the forwarding default
   — a concrete `Kv` type keeps the trait object-safe for `Box<dyn Observe>`. So
   this is *deferred*, not foreclosed. The genuine future motivation, if it
-  comes: solver-internal working state (CMA-ES σ / covariance / evolution
-  paths, LM μ / ν / diag) lives in the *solver* struct, not the state, so the
-  "expose it on a richer state trait" answer does not cover those scalars.
-  Don't "fix" the absence of a KV channel by reflex — but don't treat it as
-  permanently closed either.
+  comes: some solver-internal working state (LM μ / ν / diag) lives in the
+  *solver* struct, not the state, so the "expose it on a richer state trait"
+  answer does not cover those scalars. (CMA-ES is *no longer* an example: its
+  σ / covariance / evolution paths moved onto `CmaEsState` so its TolX test
+  could become the composable `CmaEsTolerance` criterion — see that state's
+  rustdoc.) Don't "fix" the absence of a KV channel by reflex — but don't
+  treat it as permanently closed either.
 
 - **No `Solver::name()` introspection.** The `Solver` trait (`core/solver.rs`)
   has `type Error` + `init` / `next_iter` / `terminate` and deliberately no

crates/basin-wasm/src/lib.rs

@@ -25,9 +25,9 @@ use basin::problems::{styblinski_tang, styblinski_tang_gradient};
 use basin::solver::lbfgs::{Lbfgs, Unbounded as LbfgsUnbounded};
 use basin::{
     Backtracking, BasicPopulationState, BasicSimplexState, BasicState, BoxConstraints, CmaEs,
-    Constant, CostFunction, De, DenseMatrix, Executor, FiniteDiff, Gradient, GradientDescent,
-    LbfgsState, MoreThuente, NelderMead, PopulationState, RandomSearch, Ssga, State, StepOutcome,
-    Stepper, TerminationReason,
+    CmaEsState, Constant, CostFunction, De, DenseMatrix, Executor, FiniteDiff, Gradient,
+    GradientDescent, LbfgsState, MoreThuente, NelderMead, PopulationState, RandomSearch, Ssga,
+    State, StepOutcome, Stepper, TerminationReason,
 };
 use serde::{Deserialize, Serialize};
 use wasm_bindgen::prelude::*;
@@ -298,7 +298,7 @@ type LbfgsStepper = Stepper<Problem2D, LbfgsState<Vec<f64>>, Lbfgs<LbfgsUnbounde
 /// Concrete population-solver stepper aliases. Same motivation as
 /// [`LbfgsStepper`] — keep the [`Inner`] variants readable.
 type CmaEsStepper =
-    Stepper<Problem2D, BasicPopulationState<Vec<f64>>, CmaEs<Vec<f64>, DenseMatrix>>;
+    Stepper<Problem2D, CmaEsState<Vec<f64>, DenseMatrix>, CmaEs<Vec<f64>, DenseMatrix>>;
 type DeStepper = Stepper<Problem2DBounded, BasicPopulationState<Vec<f64>>, De>;
 type RandomSearchStepper = Stepper<Problem2DBounded, BasicPopulationState<Vec<f64>>, RandomSearch>;
 type SsgaStepper = Stepper<Problem2DBounded, BasicPopulationState<Vec<f64>>, Ssga>;
@@ -602,20 +602,16 @@ impl Run {
                 } else {
                     0.25 * 0.5 * ((opts.xmax - opts.xmin) + (opts.ymax - opts.ymin))
                 };
-                let mut solver =
-                    CmaEs::<Vec<f64>, DenseMatrix>::new(initial.clone(), sigma, opts.seed);
+                let mut solver = CmaEs::<Vec<f64>, DenseMatrix>::new(opts.seed);
                 // λ < 4 is invalid for CMA-ES recombination weights; treat
                 // small overrides as "auto" and let the solver pick.
-                let lambda = if opts.cma_lambda >= 4 {
+                if opts.cma_lambda >= 4 {
                     solver = solver.with_lambda(opts.cma_lambda);
-                    opts.cma_lambda
-                } else {
-                    CmaEs::<Vec<f64>, DenseMatrix>::default_lambda(2)
-                };
+                }
                 let stepper = Executor::new(
                     p,
                     solver,
-                    BasicPopulationState::<Vec<f64>>::with_size(lambda),
+                    CmaEsState::<Vec<f64>, DenseMatrix>::new(initial.clone(), sigma),
                 )
                 .max_iter(max_iter as u64)
                 .into_stepper()

crates/basin/benches/solver_backends.rs

@@ -38,8 +38,8 @@ use std::time::Duration;
 
 use basin::problems::{Ackley, Levy, Rastrigin, Rosenbrock, SparseLeastSquares, StyblinskiTang};
 use basin::{
-    BasicPopulationState, BasicSimplexState, BasicState, Bfgs, CmaEs, DenseMatrix, Executor,
-    GaussNewton, GradientDescent, LbfgsState, Lbfgsb, LevenbergMarquardt, MoreThuente, NelderMead,
+    BasicSimplexState, BasicState, Bfgs, CmaEs, CmaEsState, DenseMatrix, Executor, GaussNewton,
+    GradientDescent, LbfgsState, Lbfgsb, LevenbergMarquardt, MoreThuente, NelderMead,
     QuasiNewtonState,
 };
 use criterion::{BatchSize, BenchmarkId, Criterion, criterion_group, criterion_main};
@@ -280,17 +280,16 @@ fn bench_cmaes(c: &mut Criterion) {
         let mut g = c.benchmark_group(format!("cmaes_rastrigin_n{n}"));
         // In-domain start away from the global optimum at the origin.
         let m0 = vec![3.0; n];
-        // λ is backend-independent; match the solver's internal default in the
-        // population state so the contract holds.
-        let lambda = CmaEs::<Vec<f64>, DenseMatrix>::default_lambda(n);
+        // The mean / σ live on `CmaEsState`; the state builder seeds it from the
+        // per-batch start vector and the solver derives λ internally.
 
         contestant!(
             g,
             "vec",
             || m0.clone(),
             Rastrigin<Vec<f64>>,
-            CmaEs::<Vec<f64>, DenseMatrix>::new(m0.clone(), 0.3, 42),
-            |_x0| BasicPopulationState::<Vec<f64>>::with_size(lambda),
+            CmaEs::<Vec<f64>, DenseMatrix>::new(42),
+            |x0| CmaEsState::<Vec<f64>, DenseMatrix>::new(x0, 0.3),
         );
 
         let m0n = DVector::from_vec(m0.clone());
@@ -299,8 +298,8 @@ fn bench_cmaes(c: &mut Criterion) {
             "nalgebra",
             || m0n.clone(),
             Rastrigin<DVector<f64>>,
-            CmaEs::<DVector<f64>, DMatrix<f64>>::new(m0n.clone(), 0.3, 42),
-            |_x0| BasicPopulationState::<DVector<f64>>::with_size(lambda),
+            CmaEs::<DVector<f64>, DMatrix<f64>>::new(42),
+            |x0| CmaEsState::<DVector<f64>, DMatrix<f64>>::new(x0, 0.3),
         );
 
         let m0f = Col::<f64>::from_fn(n, |i| m0[i]);
@@ -309,8 +308,8 @@ fn bench_cmaes(c: &mut Criterion) {
             "faer",
             || m0f.clone(),
             Rastrigin<Col<f64>>,
-            CmaEs::<Col<f64>, Mat<f64>>::new(m0f.clone(), 0.3, 42),
-            |_x0| BasicPopulationState::<Col<f64>>::with_size(lambda),
+            CmaEs::<Col<f64>, Mat<f64>>::new(42),
+            |x0| CmaEsState::<Col<f64>, Mat<f64>>::new(x0, 0.3),
         );
         g.finish();
     }

crates/basin/src/core/state.rs

@@ -18,9 +18,12 @@
 //! pipeline composes at `F = f32`, and the *Provisional choices* section of
 //! `CONTRIBUTING.md`.
 
+/// CMA-ES distribution state (`CmaEsState`).
+pub mod cma_es;
 /// Limited-memory BFGS / L-BFGS-B state (`LbfgsState`).
 pub mod lbfgs;
 
+pub use cma_es::CmaEsState;
 pub use lbfgs::LbfgsState;
 
 use crate::core::math::{MatrixIdentity, Scalar, VectorLen};
@@ -298,14 +301,20 @@ pub trait SimplexState: State {
 ///   [`costs`](Self::costs) sorted by **ascending cost** at the start
 ///   and end of every
 ///   [`Solver::next_iter`](crate::core::solver::Solver::next_iter)
-///   call (and at the end of [`Solver::init`](crate::core::solver::Solver::init)).
-///   So [`State::param`] / [`State::cost`] always return the current
-///   best candidate (`candidates[0]` / `costs[0]`).
+///   call (and at the end of [`Solver::init`](crate::core::solver::Solver::init)),
+///   so `candidates[0]` / `costs[0]` are always the best sampled
+///   candidate.
 /// - **Implementor must:** sort `NaN` costs *last*, so a single bad
 ///   evaluation can't drag itself to the front and become the
 ///   "best" candidate.
 /// - **Implementor must:** keep the two slices the same length and in
 ///   parallel order — `costs[i]` is the cost at `candidates[i]`.
+/// - What [`State::param`] / [`State::cost`] return is the [`State`]
+///   impl's responsibility and need *not* equal `candidates[0]`. Most
+///   population states (e.g. [`BasicPopulationState`]) return the best
+///   candidate; distribution-based states like
+///   [`CmaEsState`] return the distribution mean
+///   (`xfavorite`) while the population stays the sampled candidates.
 pub trait PopulationState: State {
     /// All `λ` candidates, sorted by ascending cost.
     fn candidates(&self) -> &[Self::Param];