Module contract 

SRD-86 — the core optimizer contract.

This is the service boundary the phase-execution driver uses to drive an optimizer. It is defined here, in the core runtime, with no dependency on any optimizer-algorithm crate (SRD-86 §Contract): the engine owns the contract; algorithm crates (e.g. nmbrs-optimizers) register implementations against it via inventory and are discovered at link time — the core never names them.

The contract has two halves:

• what the optimizer needs from the driver: an Objective it can query at a coordinate (the runtime’s PhaseFeed implements it);
• what the driver needs from the optimizer: an Optimizer that, over a SearchSpace within a Budget, maximizes the objective and returns a Report.

SweepOptimizer (sweep) is the built-in default (the full Cartesian sweep + best-selection) — the identity until an adaptive method is named. Algorithm crates submit an OptimizerRegistration; by_name and describe discover them.

Structs

Axis

One factor of the search space.

AxisImpact

Per-axis sensitivity, populated by screening optimizers.

Budget

Evaluation budget + reproducibility seed.

LexSource

The default lexicographic coordinate stream over a search space: the full Cartesian product of the discrete-axis detents and the {lo, hi} corners of continuous axes, in lex order, one coordinate per pull. The sweep functor returns it unchanged (identity).

Observation

One objective evaluation result.

OptimizerInfo

Name + markdown doc for one optimizer, for nmbrs describe optimizers.

OptimizerParams

Optimizer-specific tuning knobs (resolved by name with a default).

OptimizerRegistration

An optimizer implementation’s registration, submitted at link time via inventory by an algorithm crate (e.g. nmbrs-optimizers).

PullOnly

Wraps a boxed PullSource as a pull-only CoordinateSource.

Report

The result of a search.

SearchSpace

The search space the optimizer explores.

SweepOptimizer

The built-in default optimizer: the identity functor. It returns the default lexicographic stream unchanged — a full Cartesian sweep, the engine’s ordinary parameter enumeration. Always available, no plugin required (SRD-86 A1).

Enums

AxisKind

The domain of one axis.

AxisValue

The realized value an axis takes at a coordinate — the comprehension’s actual value (SRD-86 A4). The model carries labels/detents as-is; numeric casting for metric-space solvers is a solver-internal stub (the runtime bridge), never in this model.

Changeover

How an axis’s value is changed at runtime (cost prior; the runtime owns the actual realization — SRD-86 A5).

StopReason

Why a search ended (maps to a two-axis Outcome at the seam — SRD-86 A8).

Traits

CoordinateSource

A coordinate source the graph executor pulls through (SRD-86). The source advertises capability decorators; the executor probes them, favoring the most capable (FeedbackSource) and requiring at least one.

FeedbackSource

Most-capable decorator — the optimizer primitive. Given the just-evaluated (coord, objective) pairs, yield the next batch of coordinates to evaluate, or None when the search is done. The first call receives an empty slice (it produces the initial batch). Batch methods (CMA-ES generation, Hyperband bracket) return several coordinates at once and buffer the matching values across calls.

Objective

The thing an optimizer queries. The runtime’s PhaseFeed implements it by running a probe phase at the coordinate and reading the objective metric. The optimizer maximizes Observation::value.

Optimizer

A non-derivative, multi-factor optimizer — a stateless functor that transforms the default lexicographic coordinate stream into a (possibly adaptive) CoordinateSource (SRD-86). The search state lives in the produced source, not in the optimizer.

PullSource

Least-capable decorator: yield the next batch of coordinates without feedback. The default lexicographic stream and discrete reorderings are pull sources.

Functions

by_name

Resolve an optimizer by name: the built-in sweep, or a link-time registration. Returns None for an unknown name.

describe

Every available optimizer (the built-in sweep + all registrations), sorted by name, for nmbrs describe optimizers.

registered_names

Every registered optimizer name (built-in sweep + registrations).

Type Aliases

Coord

A point in the search space — one AxisValue per axis. The model carries the comprehension’s actual values, so labels survive end-to-end.