Crate atune_oniro 

The M3.3 oniro tuning spike — tune oniro end to end, with zero oniro changes, from the atune side.

This internal crate is the RL vertical of docs/design/06-roadmap.md M3 (slice plan docs/design/09-implementation.md §12; integration spec docs/design/04-rl-and-oniro.md §B). It drives oniro from outside, over the subprocess executor — process-per-trial, because oniro seeds a process-global RNG (§B.2) — and it shells out to the oniro_cli binary: it never depends on oniro as a cargo crate. The same code drives the real oniro and a contract-compatible test mock; only the ONIRO_CLI path differs.

The pipeline

1. Space — a TOML overlay ([space] table of dotted config key → string-DSL spec) lowers to a SpaceSchema. The zero-code path of §B.5 (the config_schemas() JSON-Schema path is richer but needs an oniro dependency).
2. Materialize — per trial, the sampled values are set at their dotted keys onto the base RunConfig TOML, with the CRN seed written to run.seed and a unique run directory (materialize).
3. Objective — oniro_cli run --config <trial> trains one process, then the objective is read from greedy oniro_cli eval’s mean_return (the default, RNG-free) or checkpoints/meta.json::final_metric (report).
4. TPE + multi-seed — a TPE study with a k = 3 paired (common-random-numbers) tune-seed fan, IQM aggregate, and a disjoint test-seed re-evaluation stage (harness).

Segmented trials (M4.6)

The pipeline above runs a trial as exactly one oniro run, so nothing happens between its start and its end: no intermediate value for a scheduler, no checkpoint for a population to fork from, no per-trial fidelity. The segment module turns a trial into a sequence of resumable segments instead — oniro run, then oniro run --resume <previous run dir>, with a record_checkpoint and a report at every boundary. That is what AshaPruner needs to prune at a rung and what Pbt needs to fork a child onto another trial’s run directory. Set SpikeConfig::segments to switch a spike over; everything else is unchanged.

Multi-fidelity trials (M4.7)

The other budget axis is per-trial fidelity: FidelityObjective runs each trial as one cold oniro run at a run.steps budget a FidelitySource chooses — from Dehb’s bracket schedule, or a fixed full budget for the baseline. Reporting at the fidelity charges the study’s fidelity-unit budget, so a DEHB study and a full-fidelity random study run to the same total step budget (the fidelity module).

The two binaries

• oniro-trial — the child the executor spawns once per trial (per replicate). It materializes the trial config, runs oniro, and prints the objective. Its core is child::evaluate_child; it reads its inputs from the environment via harness::child_inputs_from_env.
• oniro-tune — the human-facing driver: capture oniro_cli default-config, read an overlay, run the study, print the tune/test report. It locates its oniro-trial sibling with harness::sibling_bin.

Testability without a heavy oniro build

Everything above is exercised in the normal gate against a mock oniro_cli (a tiny program compiled at test time that speaks the same default-config/run/run --resume/eval contract over a deterministic bowl objective with an accumulating training curve): see tests/oniro_spike.rs. The real spike is the same pipeline with ONIRO_CLI pointed at a real oniro_cli binary.

Mock symmetry is an invariant (docs/design/09-implementation.md §13). The mock and the real oniro are driven by the same code, so every capability this crate grows — --resume, per-segment step budgets, the shape-parameter resume block, the learn-gate floor — must be taught to the mock as well, or the gate silently stops covering it.

Re-exports

pub use child::ChildInputs;

pub use child::evaluate_child;

pub use child::evaluate_child_with_runtime;

pub use error::Result;

pub use error::SpikeError;

pub use fidelity::FidelityObjective;

pub use fidelity::FidelitySource;

pub use harness::SamplerChoice;

pub use harness::SpikeConfig;

pub use harness::SpikeReport;

pub use harness::evaluate_config_on_test_seeds;

pub use harness::run_spike;

pub use overlay::OverlaySpace;

pub use overlay::parse_overlay;

pub use report::ObjectiveSource;

pub use runtime::CommandLineRuntime;

pub use runtime::InMemoryRuntime;

pub use runtime::MetricRequest;

pub use runtime::MetricSource;

pub use runtime::OniroRuntime;

pub use runtime::RunHandle;

pub use runtime::TrainRequest;

pub use segment::RungFloor;

pub use segment::Segment;

pub use segment::SegmentPlan;

pub use segment::SegmentedObjective;

pub use segment::fork_safe_pbt;

pub use segment::learn_floor;

pub use segment::resume_blocked_params;

Modules

child

The per-trial child’s core: materialize → run oniro → read the objective.

error

The spike’s error type.

fidelity

Multi-fidelity oniro trials: run each trial at a per-trial run.steps budget (M4.7, docs/design/09-implementation.md §13).

harness

The spike harness: build the study, drive oniro over the executor, re-rank.

materialize

Materializing one trial’s RunConfig TOML from the base config.

overlay

The search-space overlay: a TOML [space] table over the oniro config.

protocol

The env-var handshake between the harness and the per-trial child.

report

Reading a trial’s objective back out of the oniro CLI contract.

runtime

Typed runtime seam for training and measuring Oniro runs.

segment

Compatibility surface for segmented Oniro trials.