1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
//! One net, one step clock — the engine's per-net step path.
//!
//! Call graph inside a step:
//!
//! ```text
//! step_one_net(hash, clock)
//! ├─ elite freeze check (ANTI-DEVOLUTION A) → act-and-measure pass (NoopOptimizer)
//! ├─ challenge_fires(run_seed, net_seed, clock) ← anti-plateau trigger
//! └─ run_trainer_step_with_real_optimizer(hash, clock, challenged)
//! └─ run_trainer_step(hash, clock, optimizer, challenged)
//! ├─ seed_step_randomness(net_seed, clock) (fastrand + libtorch)
//! ├─ trainer.train_step(...) (the caller's scheme)
//! └─ debug contract probe (re-scores the reported eval loss)
//! ```
//!
//! The engine never trains: it seeds the two RNGs, hands the trainer one net
//! and one clock, and consumes the `StepReport`. Metric recording and rolling
//! buffers are the caller's job (the freeze pass records but skips the weight
//! update).
use flodl::tensor::Result;
use tracing::info;
use super::core::{CoreEngine, NoopOptimizer};
use super::format::{fmt_opt2, fmt2};
use crate::state::NetMetrics;
#[cfg(debug_assertions)]
use crate::utils::race_steps::eval_one_step;
impl CoreEngine {
/// Step one live net at the given step_clock: train on the shared train
/// batch, eval on the shared eval batch, record metrics into `RaceState`,
/// push fitness into the rolling buffer, overwrite `nets/<hash>.json`,
/// log one per-net line.
///
/// The net's `Network` + `Optimizer` live in the engine's maps and are
/// mutated in place — coefficients evolve across steps, optimizer state
/// carries forward. **Not rebuilt each step** (that would lose optimizer
/// state and forget prior training).
pub(crate) fn step_one_net(&mut self, hash: &str, clock: usize) -> Result<()> {
// ANTI-DEVOLUTION A — elite freeze (computed BEFORE the optimizer
// borrow): top-k nets skip the trainer call entirely. Their skill is
// the frozen state, so the "report" is the last recorded metrics —
// re-measuring would require re-running the trainer, which is
// exactly what we're skipping. Scoring, ranking, parent selection
// all proceed as normal off the carried metrics.
// The pruner phase bypasses freeze entirely: it keeps ONLY elites,
// so with freeze active every solo step would be a no-op-optimizer
// act-and-measure and the post-race workout would train nothing
// (plus every crown flip would fire the dethrone optimizer reset,
// repeatedly erasing the survivor's momentum).
let frozen = !self.pruner_solo_active
&& self.config.freeze_elites
&& self.elite_hashes().contains(&hash.to_string());
if frozen && !self.frozen_crown.contains(hash) {
// Crown transition: this net newly joined the frozen set (first
// crowning or a child trained past a frozen elite). One info
// line, only on the transition; stable steps are silent (the ★
// badge on the rollup line carries the state).
let fitness = self
.state
.net(hash)
.and_then(|s| s.last_metrics.as_ref().map(|m| m.fitness));
let seat = self.elite_hashes().len();
let pos = self
.elite_hashes()
.iter()
.position(|h| h == hash)
.map(|p| p + 1)
.unwrap_or(0);
if seat == 1 {
// Single-elite wording (the common case): crown moves as one.
if self.frozen_crown.is_empty() {
info!(
"step {} │ freeze │ champion {} crowned (fitness{} {}) — weight updates paused (act+measure continues)",
clock,
&hash[..8.min(hash.len())],
self.fitness.direction().arrow(),
fitness.map(fmt2).unwrap_or_else(|| "—".into()),
);
} else {
let prev = self.frozen_crown.iter().next().cloned().unwrap_or_default();
info!(
"step {} │ freeze │ crown moved {} → {} (fitness{} {}) — previous champion resumes weight updates",
clock,
&prev[..8.min(prev.len())],
&hash[..8.min(hash.len())],
self.fitness.direction().arrow(),
fitness.map(fmt2).unwrap_or_else(|| "—".into()),
);
}
} else {
// Multi-elite: say WHICH seat the net just took. No
// "crown moved" language — with k seats, one joining does
// not imply another was dethroned.
info!(
"step {} │ freeze │ elite seat {pos}/{seat}: {} frozen (fitness{} {}) — weight updates paused (act+measure continues)",
clock,
&hash[..8.min(hash.len())],
self.fitness.direction().arrow(),
fitness.map(fmt2).unwrap_or_else(|| "—".into()),
);
}
self.frozen_crown.insert(hash.to_string());
}
// A net that LOST the crown (it sits in `frozen_crown` but is no
// longer in the elite set) simply resumes normal stepping: frozen
// nets ACT and MEASURE every step (below), so they never fall behind
// the clock — there is no catch-up gauntlet on dethrone.
if !frozen && self.frozen_crown.contains(hash) {
self.frozen_crown.remove(hash);
// Fair-warm-up on dethrone: the optimizer STATE (momentum/velocity/
// step counters) is stale — its notes describe the gradient
// landscape of the frozen era. Resetting keeps all the weights
// (the frozen skill) and all the hyperparameters, but forgets the
// stale trend, so the first reclaim updates are clean-scaled.
// Say WHO took the seat: the new elite set minus the dethroned
// net (the seats just re-dealt). First non-dethroned elite.
let taker = self
.elite_hashes()
.into_iter()
.find(|h| h != hash)
.unwrap_or_default();
info!(
"step {} │ freeze │ {} dethroned (seat → {}) — resumes training with its last optimizer state (was acting/measuring while frozen, no catch-up needed)",
clock,
&hash[..8.min(hash.len())],
if taker.is_empty() {
"?".to_string()
} else {
taker[..8.min(taker.len())].to_string()
},
);
}
if frozen {
// ACT-AND-MEASURE freeze: the elite plays its normal step against
// the current clock (fresh batch / fresh env matches — the fitness
// input is real, so its standing stays honest and the pack can
// pass it) but the weight update is DISCARDED: the step runs
// through a no-op optimizer, leaving the frozen weights and the
// real optimizer's moments untouched.
let mut noop = NoopOptimizer;
// `challenged: false` — the freeze never co-fires with a challenge
// (act-and-measure is already the deviation from the normal step).
let report = self.run_trainer_step(hash, clock, &mut noop, false)?;
let metrics = NetMetrics {
step: clock,
train_loss: report.train_loss,
eval_loss: report.eval_loss,
fitness: report.fitness,
informative: report.informative,
frozen: true,
};
if let Some(buf) = self.rolling_fitness.get_mut(hash) {
buf.push(metrics.fitness);
}
if let Some(buf) = self.rolling_train.get_mut(hash) {
buf.push(metrics.train_loss);
}
if let Some(buf) = self.rolling_eval.get_mut(hash) {
if let Some(e) = metrics.eval_loss {
buf.push(e);
}
}
self.state.record_step(hash, metrics.clone())?;
// Persist the act-and-measure marker: replay must re-run this
// clock through the no-op optimizer (see catch_up_step).
if let Some(s) = self.state.net_mut(hash) {
s.record_frozen_step(clock);
}
tracing::debug!(
"step {} │ net {} │ FROZEN (elite) — acted+measured fitness{} {} (no weight update)",
clock,
&hash[..8.min(hash.len())],
self.fitness.direction().arrow(),
fmt2(metrics.fitness),
);
return Ok(());
}
// One step = whatever the caller's training scheme does for one step
// clock. The engine only consumes the returned report.
let optimizer_ok = self.optimizers.contains_key(hash);
if !optimizer_ok {
return Err(crate::utils::error::EngineError::InvalidOptions(format!(
"race: net {hash} not live (no Optimizer in memory)"
))
.into());
}
// Challenge trigger (anti-plateau): a per-step chance the net's step
// runs with the trainer forcing a drawn action. `prob = 0` (default)
// never fires. The roll is a pure function of (run, net, step) — see
// `challenge_fires` — so replay/catch-up re-fires identical triggers.
let net_seed = self.state.net(hash).map(|s| s.net_seed as u64).unwrap_or(0);
let challenged = crate::engine::config::challenge_fires(
self.header.run_seed,
net_seed,
clock,
self.config.challenge_prob,
self.config.max_steps,
);
let report = self.run_trainer_step_with_real_optimizer(hash, clock, challenged)?;
// Tabular challenge accounting: the trainer reports how many INPUT
// VALUES it jittered (an element-level draw), and its expectation is
// `p_eff × rows × features` per net-step. RL reports turns instead
// (the block below).
if !self.trainer.is_rl() {
self.step_challenged_inputs += report.challenged_inputs;
self.total_challenged_inputs += report.challenged_inputs;
let rows = self.stream.as_ref().map(|s| s.batch_size()).unwrap_or(0);
self.expected_challenged_inputs +=
self.effective_challenge_prob(clock) * (rows * self.header.input_dim) as f32;
}
// Turn-based challenge accounting: what the trainer REPORTS as forced
// turns is what the log counts (the trainer owns challenge semantics;
// the engine only keeps the books).
if report.challenged_turns > 0 {
self.step_rl.add_challenged(report.challenged_turns);
self.total_challenged_turns += report.challenged_turns;
}
if let Some(rl) = &report.rl {
// Run-total expectation, decay-aware: the knob at THIS step's
// decay times the turns a challenge could have forced (train
// only — eval turns are never challengeable).
self.total_train_turns += rl.train_turns;
self.expected_challenged_turns +=
self.effective_challenge_prob(clock) * rl.train_turns as f32;
}
let metrics = NetMetrics {
step: clock,
train_loss: report.train_loss,
eval_loss: report.eval_loss,
fitness: report.fitness,
informative: report.informative,
frozen: false,
};
self.state.record_step(hash, metrics.clone())?;
// A challenge is just another step: its fitness (measured under the
// forced action) ranks like any other — the user's semantics. The
// forced trajectory is part of what the net had to survive, so the
// ranking sees it.
if let Some(buf) = self.rolling_fitness.get_mut(hash) {
buf.push(metrics.fitness);
}
if let Some(buf) = self.rolling_train.get_mut(hash) {
buf.push(metrics.train_loss);
}
if let Some(buf) = self.rolling_eval.get_mut(hash) {
if let Some(e) = metrics.eval_loss {
buf.push(e);
}
}
if challenged {
tracing::debug!(
"step {} │ net {} │ CHALLENGED — fitness{} {} (trainer-applied response)",
clock,
&hash[..8.min(hash.len())],
self.fitness.direction().arrow(),
fmt2(metrics.fitness),
);
}
// Per-net detail is debug-only (Plan A: the user log shows one rollup
// line per step — see `run`). All values remain in nets/<hash>.json.
let dir = self.fitness.direction().arrow();
tracing::debug!(
"step {} │ net {} │ train_loss↓ {} │ eval_loss↓ {} │ fitness{} {}",
clock,
hash,
fmt2(metrics.train_loss),
fmt_opt2(&metrics.eval_loss),
dir,
fmt2(metrics.fitness),
);
Ok(())
}
/// The normal group step: drive one trainer step through the net's REAL
/// optimizer (weights update, momentum carries forward). Returns the
/// report plus whether a challenge actually EXECUTED (the trigger fired
fn run_trainer_step_with_real_optimizer(
&mut self,
hash: &str,
clock: usize,
challenged: bool,
) -> Result<crate::trainer::StepReport> {
let mut optimizer = self.optimizers.remove(hash).ok_or_else(|| {
crate::utils::error::EngineError::InvalidOptions(format!(
"race: net {hash} not live (no Optimizer in memory)"
))
})?;
let report = self.run_trainer_step(hash, clock, optimizer.as_mut(), challenged)?;
self.optimizers.insert(hash.to_string(), optimizer);
Ok(report)
}
/// Drive one trainer step for the live net `hash` at `clock` through the
/// given optimizer — the shared body of the normal group step and the
/// act-and-measure freeze pass (which passes a [`NoopOptimizer`]). Seeds
/// the step RNGs, runs the trainer, runs the debug contract probe, and
/// accumulates RL volume and the challenge counters; recording metrics
/// and ranking buffers is the CALLER's job (the freeze pass records
/// before returning early). A challenged step goes through the same
/// return as any other — its fitness ranks like any other.
fn run_trainer_step(
&mut self,
hash: &str,
clock: usize,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
challenged: bool,
) -> Result<crate::trainer::StepReport> {
let net_seed = self.state.net(hash).map(|s| s.net_seed as u64).unwrap_or(0);
// The EFFECTIVE (decay-adjusted) challenge probability for this step —
// the per-(input, feature) rate an element-level tabular response
// should roll against. Same number the trigger used (one function).
let challenge_prob = self.effective_challenge_prob(clock);
// The mode decides the context: Tabular receives the run's data
// handle (guaranteed present by construction), RL receives none.
let run_data = self
.dataset
.as_ref()
.zip(self.stream.as_ref())
.map(|(dataset, stream)| crate::trainer::RunData { dataset, stream });
let env = crate::trainer::StepEnv {
step: clock,
run_seed: self.header.run_seed,
pop_size: self.config.pop_size,
live_count: self.state.live_count(),
checkpoint_every: self.config.checkpoint_every,
smoothing_window: self.config.smoothing_window,
max_steps: self.config.max_steps,
};
let net = self.networks.get_mut(hash).ok_or_else(|| {
crate::utils::error::EngineError::InvalidOptions(format!(
"race: net {hash} not live (no Network in memory)"
))
})?;
// Seed BOTH RNGs for this (net, step) before the trainer runs: gras's
// fastrand stream and libtorch's global RNG (dropout masks). Without
// the libtorch seed a `dropout_prob > 0` net redraws different masks
// on replay and breaks resume parity. The engine owns this because
// the trainer — any trainer — may draw masks inside `train_step`.
crate::utils::race_steps::seed_step_randomness(net_seed, clock as u64, 0);
// The challenge SIGNAL: the engine pre-rolled the trigger and hands
// the flag to the trainer — the TRAINER decides what a challenge means
// (force a drawn action, perturb the env, whatever its env needs).
// A trainer that ignores the flag simply never challenges (keep the
// knob at 0); the engine does not verify the flag was honored. What
// the trainer reports in `challenged_turns` is what the log shows.
let report = self.trainer.train_step(
net,
optimizer,
clock,
run_data.as_ref(),
&self.fitness,
&self.metrics,
env,
hash,
net_seed,
challenged,
challenge_prob,
)?;
// Debug-only contract probe: the Trainer's per-step clause says the
// report describes the net AFTER this step's training. Re-score the
// net on the step's eval batch and check the reported eval loss is
// what this net actually scores — catches a stale/fabricated report
// at development time. Zero cost in release.
#[cfg(debug_assertions)]
// Tabular-only: the probe needs an eval batch + a computed fitness
// scorer. RL mode has neither (reported fitness, no dataset).
if let (Some(reported), Some(net), Some(stream), Some(dataset), true) = (
report.eval_loss,
self.networks.get_mut(hash),
self.stream.as_ref(),
self.dataset.as_ref(),
self.fitness.is_computed(),
) {
let eval_batch = stream
.eval_batch(dataset, clock as u64)
.expect("probe: eval batch");
if let (Some(loss), Some(fit)) = (self.trainer.tabular_loss(), Some(&self.fitness)) {
if let Ok(actual) = eval_one_step(net, loss, fit, &self.metrics, &eval_batch) {
if let Some(actual_loss) = actual.eval_loss {
let rel = ((reported - actual_loss).abs()) / actual_loss.abs().max(1e-6);
assert!(
rel < 1e-3,
"trainer contract violated: step {clock} net {hash} reported eval_loss {reported:.6} but the net scores {actual_loss:.6} — the StepReport must describe the net's state at the end of this step"
);
}
}
}
}
// RL volume: the trainer's reported environment work for this step
// accumulates across the group so the rollup can show the step's real
// workload (matches + turns). Tabular trainers report `None`.
if let Some(rl) = report.rl {
self.step_rl.nets += 1;
self.step_rl.matches += rl.matches;
self.step_rl.train_turns += rl.train_turns;
self.step_rl.eval_turns += rl.eval_turns;
}
Ok(report)
}
}