Optimization role — native hyperparameter finetuning

The optimization role (C ABI header n4m/optimization.h, ABI 2.1) is a portable ask/tell hyperparameter optimizer: the search algorithm lives once in libn4m and is reused by every binding, so finetuning is bit-reproducible across Python / R / MATLAB-Octave / WASM. Design rationale and the full plan are in FINETUNING_ROADMAP.md and NATIVE_FINETUNING.md; the ABI freeze is detailed in FINETUNING_F0_PR.md.

Model

Three objects, all opaque C-ABI handles:

• n4m_search_space_t — a typed set of parameters (int, float, log_int, log_float, categorical with typed values, ordinal, sorted_tuple) plus declarative constraints (mutex_group, requires, exclude, condition_in/_not_in). Built with n4m_search_space_add_*.

• n4m_optimizer_t — the stateful search. ask() proposes a trial; the host evaluates it however it likes; tell() / tell_result() reports the outcome (completed / pruned / failed, with a score). tell_intermediate() reports a fidelity-rung score for pruning. best() returns the incumbent; get_trials() streams the trace; enqueue() warm-starts a known configuration.

• n4m_trial_t — one proposed configuration (borrowed; owned by the optimizer). Read parameters with n4m_trial_get_int/float/category, activation with n4m_trial_is_active.

The host drives the loop (ask → evaluate → tell); there is no C→host objective callback, so the pattern is safe under R’s non-reentrant evaluator, WASM’s synchronous runtime, and Python’s GIL. For a native model the loop is wrapped in one call: n4m_finetune_estimator runs the ask/tell loop with an internal cross-validation objective (F0: PLS n_components).

Samplers and pruners

Selected via n4m_optimizer_options_t.sampler / .pruner. Algorithms sit behind reserved enum values; a value not yet implemented returns N4M_ERR_NOT_IMPLEMENTED at n4m_optimizer_create, so activating one in a later phase adds no new ABI symbol.

Kind	Status	Phase	Page
sampler random	✅ implemented	F0	random.md
sampler ternary	✅ implemented	F1	ternary.md
sampler lhs	✅ implemented	F1	lhs.md
sampler ga	✅ implemented	F3	ga_search.md
sampler pso	✅ implemented	F3	pso_search.md
sampler cmaes	✅ implemented	F4	cmaes.md
sampler tpe	✅ implemented	F4	tpe.md
sampler sobol	reserved	F1	—
sampler gp_ei	reserved / optional	F4	—
pruner none	✅ implemented	F0	—
pruner median	✅ implemented	F2	median_pruner.md
pruner asha	✅ implemented	F2	asha.md
pruner racing	✅ implemented	F2	racing.md
pruner hyperband	reserved	F2/F5	—

Reproducibility

The optimizer owns a seeded n4m_rng; the same seed and the same sequential tell-order reproduce the exact ask sequence, identically in every binding (the cross-binding parity guarantee). Parity tiers per sampler are described in FINETUNING_ROADMAP.md §3.