gras 1.1.2

A Genetic Programming framework for Neural Architecture Search in Rust
Documentation
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
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
//! DECISION-LAG relay — an RL experiment, isolated behind one wrapper type.
//!
//! **The problem it attacks:** an RL net that learns through its own actions
//! sits in a closed feedback loop — as the net learns, the games it plays
//! unfold differently, so its training distribution shifts under its own
//! feet mid-stride. The loop can reinforce itself and stall learning.
//!
//! **The scheme:** per step, the net's CURRENT weights (the *face*) play the
//! deciding matches and report the fitness evolution ranks on — but never
//! train. A SHADOW copy (forked from the face at the last step boundary)
//! plays its own matches and receives the real optimizer step. At the step
//! boundary the shadow is PROMOTED: its weights become the next face, and a
//! fresh shadow is forked from it. The deciding policy is therefore always
//! exactly one step behind its own learning — the game the face plays today
//! cannot reinforce what the face learned on.
//!
//! The relay width is configurable: `.with_lag(k)` makes a cycle span `k`
//! engine steps — the face holds its weights for all of them, the shadow takes
//! `k` optimizer steps, and promotion happens on the cycle's last step.
//!
//! **Conservative defaults (both knobs unset):** `::new(inner)` starts with
//! `lag = 0` — the relay is OFF, the wrapper is a plain pass-through — and
//! `grace = 5` — the first 5 engine steps are plain per-net training (no
//! relay) before anything engages. `.with_lag(k)` opts the relay in
//! (`k ≥ 1`; `k = 0` turns it back off); `.with_grace(n)` overrides the
//! warm-up (`0` = engage immediately). Grace is a pure *absence* of the
//! relay: inert while `lag = 0`, and with `lag ≥ 1` the relay engages at
//! step `n` with its first full cycle (the cycle clock is measured from the
//! end of the grace period).
//!
//! **Where it lives:** entirely inside this wrapper. The engine calls
//! `train_step(&mut net, ...)` exactly as before and consumes the returned
//! report; the wrapper decides which weights play, which learn, and when to
//! promote. No engine changes, no new engine state — to remove the experiment,
//! delete this file and unwrap the trainer at the call sites.
//!
//! **Cost:** 2× matches per step (the face's deciding set + the shadow's
//! learning set). For a Python-bridge env that doubles wall time — measure
//! before enabling on a full kagi race.
//!
//! **Identity:** externally the net is still ONE individual — the engine's
//! hash, lineage, history rows, culls and exports all describe the face,
//! which is the only weights that ever decide or rank.

use crate::graph::network::Network;
use crate::trainer::core::{RlContext, RlStep, RlStepReport, StepEnv, StepTrainer};

/// The decision-lag relay around any [`RlStep`] trainer. See the module docs.
///
/// Construction: [`DecisionLagTrainer::new`], then optionally
/// [`.with_lag(k)`](DecisionLagTrainer::with_lag) to opt the relay in and
/// [`.with_grace(n)`](DecisionLagTrainer::with_grace) to widen (or close) the
/// plain-training warm-up. Both are conservative when unset: lag 0 (relay
/// off), grace 5.
pub struct DecisionLagTrainer<T: RlStep> {
    inner: T,
    /// Engine steps per relay cycle: the face HOLDS its weights for this many
    /// steps, and the shadow takes this many optimizer steps before it is
    /// promoted. `0` (the default) = relay OFF, a plain pass-through;
    /// `1` = the classic one-step relay.
    lag: usize,
    /// Engine steps of PLAIN per-net training before the relay engages
    /// (default 5). During grace the face trains directly — no held weights,
    /// no shadow, no promotions. Inert while `lag = 0`. The relay cycle is
    /// measured from the END of the grace period, so the first cycle after
    /// engagement is always a full `lag` steps.
    grace: usize,
    /// Steps since the last promotion (diagnostic; also useful for tests).
    /// The shadow itself never persists across steps (a flodl `Network` is
    /// `!Send` — it cannot live in the wrapper, which the engine requires to
    /// be `Send`): a cycle's shadow work runs inside a single `train_step`
    /// call, and the promotion is keyed off `step` alone, so the wrapper is a
    /// pure function of (weights, step) — required for replay/resume parity.
    /// The face that decides at step N is the shadow trained at the last
    /// cycle boundary, i.e. at most `lag` steps behind its own learning.
    pub steps_since_promotion: usize,
    /// Relay telemetry: counters accumulate across the calls that share a
    /// `step` and are reported when the step number changes. The engine also
    /// drives `train_step` from its REPLAY paths (resume catch-up and the
    /// crossover gate's candidate replay), so a tally can describe a replayed
    /// child rather than the live population — hence the activation banner is
    /// INFO, the tallies are DEBUG, and a stalled promotion is a WARN (always
    /// visible, at every level).
    relay: RelayStats,
}

/// Per-step relay counters (see [`DecisionLagTrainer::relay`]).
#[derive(Default)]
struct RelayStats {
    /// The step the counters belong to — `None` before the first call.
    step: Option<usize>,
    /// Nets whose deciding pass ran on HELD (frozen) weights this step.
    faces: usize,
    /// Shadows that completed a promotion with CHANGED weights this step.
    promoted: usize,
    /// Shadows whose promotion left the weights bit-identical: the relay is
    /// not learning (lr 0, saturated net, or a broken fork).
    stalled: usize,
}

impl<T: RlStep> DecisionLagTrainer<T> {
    /// Wrap an RL trainer with the decision-lag relay. Conservative
    /// defaults when no builder is called: `lag = 0` (relay OFF — the
    /// wrapper is a plain pass-through) and `grace = 5` (5 plain per-net
    /// steps before anything engages). Opt in with
    /// [`.with_lag(k)`](Self::with_lag) and tune the warm-up with
    /// [`.with_grace(n)`](Self::with_grace).
    pub fn new(inner: T) -> Self {
        DecisionLagTrainer {
            inner,
            lag: 0,
            grace: 5,
            steps_since_promotion: 0,
            relay: RelayStats::default(),
        }
    }

    /// Widen the relay to `k` ENGINE STEPS per face: the deciding face holds
    /// its weights for `k` steps (ranking on the same policy throughout),
    /// while the shadow takes `k` optimizer steps, and the promotion happens
    /// on the cycle's last step. `k ≥ 1` engages the relay (`k = 1` is the
    /// classic one-step relay; larger `k` widens the gap between the policy
    /// that acts and the policy that learns); `k = 0` (the default) leaves
    /// it OFF — the wrapper trains plainly.
    ///
    /// **Cost profile:** the shadow's `k` steps are batched onto the cycle's
    /// last step, so that step costs ≈ k× a normal one (the engine's `took Xs`
    /// column shows the spikes) while the other k−1 steps cost one face pass
    /// each. Amortized env per engine step is still ≈ 2×.
    pub fn with_lag(mut self, k: usize) -> Self {
        self.lag = k;
        self
    }

    /// The configured lag, in engine steps (`0` = relay off).
    pub fn lag(&self) -> usize {
        self.lag
    }

    /// Plain per-net training for the first `n` engine steps before the
    /// relay engages (default `5`; `0` = relay from step 0). Inert while
    /// the relay is off (`lag = 0`). The relay's cycle clock is measured
    /// from the end of the grace period, so engagement always starts a full
    /// `lag`-step cycle rather than landing mid-cycle.
    pub fn with_grace(mut self, n: usize) -> Self {
        self.grace = n;
        self
    }

    /// The configured grace width, in engine steps (default 5).
    pub fn grace(&self) -> usize {
        self.grace
    }
}

impl<T: RlStep> StepTrainer for DecisionLagTrainer<T> {
    fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
        self.inner.make_optimizer(net)
    }

    fn describe(&self) -> Option<serde_json::Value> {
        let base = self.inner.describe();
        Some(match base {
            Some(mut v) => {
                if let Some(obj) = v.as_object_mut() {
                    // `decision_lag` records whether the relay is actually
                    // engaged (lag ≥ 1); a lag-0 wrapper trains plainly.
                    obj.insert("decision_lag".into(), serde_json::json!(self.lag > 0));
                    // The lag and grace are part of the training recipe:
                    // carrying them in the blob makes `resume` refuse a
                    // different lag or grace loudly instead of silently
                    // continuing under new semantics.
                    obj.insert("decision_lag_steps".into(), serde_json::json!(self.lag));
                    obj.insert("grace_periods".into(), serde_json::json!(self.grace));
                }
                v
            }
            None => serde_json::json!({
                "decision_lag": self.lag > 0,
                "decision_lag_steps": self.lag,
                "grace_periods": self.grace
            }),
        })
    }
}

impl<T: RlStep> RlStep for DecisionLagTrainer<T> {
    fn train_step(
        &mut self,
        net: &mut Network,
        optimizer: &mut dyn flodl::nn::optim::Optimizer,
        step: usize,
        ctx: &RlContext<'_>,
    ) -> flodl::tensor::Result<RlStepReport> {
        // ── 0. Relay off (the conservative default: lag 0) ─────────────
        // A plain pass-through: the net trains directly every step — no
        // face-hold, no shadow, no promotions. Grace is inert here.
        if self.lag == 0 {
            return self.inner.train_step(net, optimizer, step, ctx);
        }

        // ── 0b. Grace period: plain per-net training before the relay ───
        // Default 5 steps (see `with_grace`). The face trains directly —
        // nothing is held, nothing is promoted — and the relay engages at
        // step `grace` with its first FULL cycle (the cycle clock below is
        // measured from the end of the grace period). Counters and the
        // activation banner start at engagement, not during the warm-up.
        if step < self.grace {
            tracing::debug!(
                "decision-lag grace step {step}/{}: plain per-net training (relay engages at step {})",
                self.grace,
                self.grace
            );
            return self.inner.train_step(net, optimizer, step, ctx);
        }

        // ── 0c. Relay telemetry ────────────────────────────────────────
        // One banner at first use (INFO — the always-on "the scheme is on"
        // signal), then one tally per step-number change at DEBUG. The tally
        // is DEBUG on purpose: the engine also drives `train_step` from its
        // REPLAY paths (resume catch-up, and the crossover gate's
        // `catch_up_range_provisional`, which walks a single candidate child
        // step-by-step) — a replay of one child emits one call per replayed
        // step, so a tally can show "1 face decision" for steps 0..N mid-way
        // through a much later live step. That is expected traffic, not the
        // live population stepping, so it stays out of the default log. A
        // stall is a WARN either way (visible at every level).
        if self.relay.step != Some(step) {
            if let Some(prev) = self.relay.step {
                tracing::debug!(
                    "decision-lag step {} (lag {}): {} face decision(s) on frozen weights │ {} shadow promotion(s) │ {} stalled",
                    prev,
                    self.lag,
                    self.relay.faces,
                    self.relay.promoted,
                    self.relay.stalled,
                );
            } else {
                let grace_note = if self.grace > 0 {
                    format!(", after a {}-step grace period", self.grace)
                } else {
                    String::new()
                };
                tracing::info!(
                    "decision-lag relay active (lag {} engine step(s){}): each net DECIDES and ranks on held (frozen) weights while a shadow forked from them takes its optimizer step(s) and is promoted at the cycle boundary — ≈2× env per step",
                    self.lag,
                    grace_note
                );
            }
            self.relay = RelayStats {
                step: Some(step),
                ..RelayStats::default()
            };
        }
        self.relay.faces += 1;

        // ── 1. The FACE decides ─────────────────────────────────────────
        // The engine handed us the face (`net`) + its optimizer. Run the
        // inner trainer on it — it plays the deciding matches and reports.
        // Its transient backward is DISCARDED right after by restoring the
        // pre-step weights: the face never learns.
        let face_weights_before = net.export_weights()?;
        let face_report = self.inner.train_step(net, optimizer, step, ctx)?;
        net.import_weights(&face_weights_before)?;

        // ── 2. The SHADOW learns (only on the cycle's last step) ────────
        // The cycle spans `lag` engine steps: the face holds its weights for
        // all of them (step 1 restores them), and the shadow's `lag` optimizer
        // steps run together on the LAST one. Batching the shadow is what
        // keeps the wrapper STATELESS: one shadow step per engine step would
        // need the shadow's weights kept per net between calls, and the
        // engine's replay paths (resume catch-up replays net-by-net, the gate
        // replays child-by-child) visit nets in a different order than the
        // live step loop — interleaved state would then diverge. Staying a
        // pure function of (weights, step) is what keeps replay bit-exact.
        let lag = self.lag;
        // The cycle clock is RELATIVE to the grace period: engagement at
        // step `grace` starts the first full cycle there (grace 0 keeps the
        // original absolute alignment). `step >= grace` is guaranteed by
        // the grace early-return above.
        let rel = step - self.grace;
        let boundary = (rel + 1) % lag == 0;
        // First engine step of the current cycle (`saturating` for cycles
        // whose opening steps land before engagement — clamped to `grace`,
        // so the shadow never replays a grace step).
        let cycle_start = self.grace + (rel + 1).saturating_sub(lag);
        let mut promoted: Option<Vec<f32>> = None;
        if boundary {
            // Fork the shadow from the face's PRE-STEP weights (the deciding
            // state), then run the inner trainer on it `lag` times: the shadow
            // plays its own matches (fresh env, on-policy for the shadow) and
            // its optimizer steps are the only learning that survives.
            let blueprint = net.topology_blueprint();
            let mut shadow_net = Network::build(&blueprint, net_device(net))?;
            shadow_net.import_weights(&face_weights_before)?;
            // The shadow's optimizer is created fresh and dropped with the
            // shadow — the relay measures lagged learning, not Adam momentum
            // transfer (the engine-owned face optimizer stays untouched).
            let mut shadow_opt = self.inner.make_optimizer(&shadow_net);
            for i in 0..lag {
                let s = cycle_start + i;
                // net_seed mixes the shadow salt AND the step offset so each
                // of the `lag` steps draws its own matches — deterministic in
                // (net_seed, step), so replays reproduce it exactly.
                let shadow_ctx = RlContext {
                    fitness: ctx.fitness,
                    metrics: ctx.metrics,
                    env: StepEnv { step: s, ..ctx.env },
                    net_hash: ctx.net_hash,
                    // Shadow steps are measurement, never challenges.
                    challenged: false,
                    net_seed: ctx
                        .net_seed
                        .wrapping_add(0x9E37_79B9_7F4A_7C15)
                        .wrapping_add(i as u64),
                };
                self.inner
                    .train_step(&mut shadow_net, shadow_opt.as_mut(), s, &shadow_ctx)?;
            }
            promoted = Some(shadow_net.export_weights()?);
        }

        // ── 3. Cycle boundary: PROMOTE the shadow ──────────────────────
        // The learned weights become the next face: install them into the
        // net the engine holds. The next `lag` steps then decide on exactly
        // this learner — the loop is broken by the lag, not by freezing
        // forever.
        match promoted {
            Some(promoted) => {
                net.import_weights(&promoted)?;
                self.steps_since_promotion = 0;
                // ── 4. Telemetry: did the shadow actually learn? ────────
                // A promotion whose weights did not move is a silent failure
                // of the whole scheme — the face would hold forever. Report
                // it loudly (WARN survives every log level) and keep the
                // per-net detail at DEBUG.
                if promoted == face_weights_before {
                    self.relay.stalled += 1;
                    tracing::warn!(
                        "decision-lag [{}] step {step}: shadow promotion changed no weights — the relay is NOT learning (lr 0? saturated net?); the face will not evolve",
                        ctx.net_hash,
                    );
                } else {
                    self.relay.promoted += 1;
                    tracing::debug!(
                        "decision-lag [{}] step {step}: face fit {:.4} (deciding pass on held weights) → shadow took {lag} step(s) & was promoted",
                        ctx.net_hash,
                        face_report.fitness,
                    );
                }
            }
            None => {
                self.steps_since_promotion += 1;
                tracing::debug!(
                    "decision-lag [{}] step {step}: face decided on held weights; shadow trains at the cycle boundary (lag {lag})",
                    ctx.net_hash,
                );
            }
        }

        Ok(face_report)
    }
}

/// The device a live net was built on — read off its first layer (every
/// layer shares the net's device by construction).
fn net_device(net: &Network) -> flodl::Device {
    net.layers
        .first()
        .map(|l| l.weight.variable.data().device())
        .unwrap_or(flodl::Device::CPU)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::fitness::{Direction, Fitness};
    use crate::trainer::core::{RlContext, StepEnv};
    use flodl::nn::Module;

    /// Minimal RL trainer: fitness = net.forward(specific input)'s first
    /// output value (so weight changes ARE observable in fitness), one
    /// pseudo-gradient step through the provided optimizer.
    struct ProbeTrainer {
        lr: f64,
    }

    impl StepTrainer for ProbeTrainer {
        fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
            use flodl::nn::Module;
            Box::new(flodl::nn::Adam::new(&net.parameters(), self.lr))
        }
    }

    impl RlStep for ProbeTrainer {
        fn train_step(
            &mut self,
            net: &mut Network,
            optimizer: &mut dyn flodl::nn::optim::Optimizer,
            _step: usize,
            _ctx: &RlContext<'_>,
        ) -> flodl::tensor::Result<RlStepReport> {
            use flodl::nn::Module;
            // Differentiable scalar: mean of the net's output. Trainable.
            let x = flodl::Variable::new(
                flodl::Tensor::from_f32(&[0.5; 4], &[1, 4], flodl::Device::CPU)?,
                true,
            );
            let out = net.forward(&x)?;
            let loss = out.mean()?;
            loss.set_requires_grad(true)?;
            optimizer.zero_grad();
            loss.backward()?;
            optimizer.step()?;
            let fit = out.mean()?.item().unwrap_or(0.0) as f32;
            Ok(RlStepReport {
                train_loss: 0.0,
                fitness: fit,
                informative: vec![],
                challenged_turns: 0,
                rl: None,
            })
        }
    }

    fn ctx(step: usize) -> RlContext<'static> {
        // Leak-free statics: the context only borrows config-level data for
        // the call duration; the test constructs it with leaked refs (test-
        // scoped, bounded).
        let fitness: &'static Fitness =
            Box::leak(Box::new(Fitness::reported(Direction::Maximize, "reward")));
        let metrics: &'static [crate::engine::fitness::Metric] = &[];
        RlContext {
            fitness,
            metrics,
            challenged: false,
            env: StepEnv {
                step,
                run_seed: 42,
                pop_size: 2,
                live_count: 2,
                checkpoint_every: 100,
                smoothing_window: 10,
                max_steps: Some(100),
            },
            net_hash: "probe",
            net_seed: 7,
        }
    }

    fn probe_net() -> Network {
        let mut topo = crate::graph::topology::Topology::new(0, None);
        topo.options.input_dim = Some(4);
        topo.options.output_dim = Some(2);
        topo.nodes.push(crate::graph::node::Node::new_input(0, 1));
        topo.nodes
            .push(crate::graph::node::Node::new_output(1, 1, 1));
        topo.finalize();
        Network::build(&topo, flodl::Device::CPU).unwrap()
    }

    #[test]
    fn relay_face_never_moves_and_shadow_promotes() {
        // After one lagged step, the face's weights equal the PROMOTED
        // shadow's — and both differ from the pre-step face ONLY IF the
        // shadow learned. The core invariant: the face that decides next
        // step is the shadow that learned this step.
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(1)
            .with_grace(0);
        let mut face = probe_net();
        let face_start = face.export_weights().unwrap();
        let mut face_opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);

        let report = lagged
            .train_step(&mut face, &mut face_opt, 0, &ctx(0))
            .unwrap();

        // The face moved (it now carries the PROMOTED shadow's weights).
        let face_after = face.export_weights().unwrap();
        assert_ne!(
            face_start, face_after,
            "promotion must install learned weights into the face"
        );
        // The report the engine ranks on is the FACE's (the pre-promotion
        // decision pass) — its fitness describes the pre-step face.
        assert!(report.fitness.is_finite());
        assert_eq!(
            lagged.steps_since_promotion, 0,
            "promotion resets the clock"
        );
    }

    #[test]
    fn relay_report_describes_the_deciding_face_not_the_learner() {
        // Two consecutive steps: the step-N report must describe the weights
        // the step-N DECISIONS were made with — the promoted face from step
        // N-1, not the shadow learning during step N. Detect by making the
        // probe trainer's fitness a function of the current weights: after
        // step 0's promotion, step 1's reported fitness must match what the
        // step-1 face scores BEFORE any learning (the promoted weights),
        // which is exactly what a pre-learning forward gives.
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(1)
            .with_grace(0);
        let mut face = probe_net();
        let mut face_opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);

        let _ = lagged
            .train_step(&mut face, &mut face_opt, 0, &ctx(0))
            .unwrap();
        // Face after step 0 = promoted shadow. Step 1's report describes
        // THIS face (pre-step-1-learning). Assert the face's weights at this
        // instant survive step 1's transient backward: capture, step, then
        // the report must be re-derivable from the captured weights.
        let face_before_step1 = face.export_weights().unwrap();
        let report1 = lagged
            .train_step(&mut face, &mut face_opt, 1, &ctx(1))
            .unwrap();

        // Replay the deciding pass on a copy of the captured weights: the
        // probe's fitness is the forward mean, so re-scoring the captured
        // weights (without the optimizer step) reproduces the report.
        let mut replay = probe_net();
        replay.import_weights(&face_before_step1).unwrap();
        let x = flodl::Variable::new(
            flodl::Tensor::from_f32(&[0.5; 4], &[1, 4], flodl::Device::CPU).unwrap(),
            false,
        );
        let out = replay.forward(&x).unwrap();
        let expected = out.mean().unwrap().item().unwrap() as f32;
        assert!(
            (report1.fitness - expected).abs() < 1e-5,
            "report {} must describe the deciding face ({expected})",
            report1.fitness
        );
    }

    #[test]
    fn lag_k_holds_the_face_for_k_steps_then_promotes() {
        // With lag 3 the face must keep bit-identical weights across steps 0
        // and 1 (no promotion) and only move on step 2, the cycle boundary.
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(3)
            .with_grace(0);
        let mut face = probe_net();
        let mut opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);
        let held = face.export_weights().unwrap();

        lagged.train_step(&mut face, &mut opt, 0, &ctx(0)).unwrap();
        assert_eq!(
            face.export_weights().unwrap(),
            held,
            "step 0 holds the face"
        );
        assert_eq!(lagged.steps_since_promotion, 1);

        lagged.train_step(&mut face, &mut opt, 1, &ctx(1)).unwrap();
        assert_eq!(
            face.export_weights().unwrap(),
            held,
            "step 1 holds the face"
        );
        assert_eq!(lagged.steps_since_promotion, 2);

        lagged.train_step(&mut face, &mut opt, 2, &ctx(2)).unwrap();
        assert_ne!(
            face.export_weights().unwrap(),
            held,
            "step 2 is the cycle boundary and promotes the shadow"
        );
        assert_eq!(
            lagged.steps_since_promotion, 0,
            "promotion resets the clock"
        );
    }

    #[test]
    fn with_lag_zero_disables_the_relay() {
        // Conservative default: lag 0 means the relay never engages — the
        // wrapper is a plain pass-through (the shadow would have nothing to
        // promote at lag 0, so "off" is the honest meaning).
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(0)
            .with_grace(0);
        assert_eq!(lagged.lag(), 0, "0 = relay off");
        let mut face = probe_net();
        let start = face.export_weights().unwrap();
        let mut opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);
        lagged.train_step(&mut face, &mut opt, 0, &ctx(0)).unwrap();
        assert_ne!(
            start,
            face.export_weights().unwrap(),
            "lag 0 trains plainly — the face moves"
        );
        assert_eq!(
            lagged.steps_since_promotion, 0,
            "no promotion ever happened"
        );
    }

    #[test]
    fn conservative_defaults_lag_off_grace_five() {
        // Both knobs unset: relay OFF (lag 0) and a 5-step grace warm-up.
        let d = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 });
        assert_eq!(d.lag(), 0, "unset lag = relay off (conservative)");
        assert_eq!(d.grace(), 5, "unset grace = 5 plain steps");
        // And the blob tells `resume` the truth: relay not engaged, 5 grace.
        let blob = d.describe().unwrap();
        assert_eq!(blob["decision_lag"], serde_json::json!(false));
        assert_eq!(blob["decision_lag_steps"], serde_json::json!(0));
        assert_eq!(blob["grace_periods"], serde_json::json!(5));
    }

    #[test]
    fn grace_defers_relay_engagement_then_runs_a_full_cycle() {
        // grace 2 + lag 3: steps 0-1 are PLAIN (the face trains directly),
        // the relay engages at step 2 with its first FULL cycle — hold at
        // rel 0 and 1 (steps 2,3), promote at rel 2 (step 4).
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(3)
            .with_grace(2);
        let mut face = probe_net();
        let mut opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);

        // Grace: the face trains every step (nothing is held).
        let s0 = face.export_weights().unwrap();
        lagged.train_step(&mut face, &mut opt, 0, &ctx(0)).unwrap();
        let s1 = face.export_weights().unwrap();
        assert_ne!(s0, s1, "grace step 0 trains plainly");
        lagged.train_step(&mut face, &mut opt, 1, &ctx(1)).unwrap();
        let s2 = face.export_weights().unwrap();
        assert_ne!(s1, s2, "grace step 1 trains plainly");
        assert_eq!(lagged.steps_since_promotion, 0, "no promotion during grace");

        // Engagement: rel 0 (step 2) holds the face…
        lagged.train_step(&mut face, &mut opt, 2, &ctx(2)).unwrap();
        assert_eq!(face.export_weights().unwrap(), s2, "rel 0 holds the face");
        assert_eq!(lagged.steps_since_promotion, 1);
        // rel 1 (step 3) holds too…
        lagged.train_step(&mut face, &mut opt, 3, &ctx(3)).unwrap();
        assert_eq!(face.export_weights().unwrap(), s2, "rel 1 holds the face");
        assert_eq!(lagged.steps_since_promotion, 2);
        // rel 2 (step 4) is the cycle boundary: the shadow (3 optimizer
        // steps over steps 2..=4) is promoted into the face.
        lagged.train_step(&mut face, &mut opt, 4, &ctx(4)).unwrap();
        assert_ne!(
            face.export_weights().unwrap(),
            s2,
            "boundary promotes the first full cycle"
        );
        assert_eq!(
            lagged.steps_since_promotion, 0,
            "promotion resets the clock"
        );
    }

    #[test]
    fn describe_declares_the_relay_and_its_lag() {
        // The engine persists this blob and `resume` compares it, so the lag
        // and grace must ride along — resuming under different values would
        // silently change the training recipe.
        let lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 }).with_lag(4);
        let blob = lagged.describe().unwrap();
        assert_eq!(blob["decision_lag"], serde_json::json!(true));
        assert_eq!(blob["decision_lag_steps"], serde_json::json!(4));
        assert_eq!(
            blob["grace_periods"],
            serde_json::json!(5),
            "unset grace rides the blob at its default"
        );
    }

    #[test]
    fn relay_telemetry_counts_faces_per_step_and_rolls_at_the_boundary() {
        // The engine calls train_step once per live net with the SAME step;
        // the telemetry must group those calls into one step's totals and
        // roll over when the clock advances (this is what the INFO line
        // reports).
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(1)
            .with_grace(0);
        let mut a = probe_net();
        let mut b = probe_net();
        let mut oa = flodl::nn::Adam::new(&a.parameters(), 1e-2);
        let mut ob = flodl::nn::Adam::new(&b.parameters(), 1e-2);
        lagged.train_step(&mut a, &mut oa, 0, &ctx(0)).unwrap();
        lagged.train_step(&mut b, &mut ob, 0, &ctx(0)).unwrap();
        assert_eq!(lagged.relay.faces, 2, "both nets of step 0 counted");
        assert_eq!(
            lagged.relay.promoted + lagged.relay.stalled,
            2,
            "each net's promotion is classified exactly once"
        );
        // Advancing the clock starts a fresh tally for the new step.
        lagged.train_step(&mut a, &mut oa, 1, &ctx(1)).unwrap();
        assert_eq!(lagged.relay.step, Some(1));
        assert_eq!(lagged.relay.faces, 1);
    }
    #[test]
    fn relay_promotion_actually_learns_face_moves_over_steps() {
        // The point of the scheme: the face should IMPROVE over relay steps
        // (the shadow is minimizing the probe loss; fitness = pre-loss mean
        // of outputs, which the probe's backward drives toward its minimum).
        // Assert direction of travel, not magnitude.
        let mut lagged = DecisionLagTrainer::new(ProbeTrainer { lr: 1e-2 })
            .with_lag(1)
            .with_grace(0);
        let mut face = probe_net();
        let mut face_opt = flodl::nn::Adam::new(&face.parameters(), 1e-2);
        let start = face.export_weights().unwrap();
        for step in 0..5 {
            let _ = lagged
                .train_step(&mut face, &mut face_opt, step, &ctx(step))
                .unwrap();
        }
        let end = face.export_weights().unwrap();
        assert_ne!(start, end, "five relay steps must move the face");
    }
}