data(vardiff_sim): design doc + baseline characterization of VardiffState

- VARDIFF_SIMULATION_FRAMEWORK.md: design proposal documenting the
  framework's five metrics, assertion policy, simulation mechanism,
  and architectural rationale. Co-located with the crate it describes.

- vardiff_baseline.toml: machine-readable baseline measurements of
  the classic VardiffState algorithm across the default 50-cell grid
  (5 share rates × 10 scenarios, 1000 trials each, base seed
  0xDEADBEEFCAFEF00D). Consumed by the regression test in the sim
  crate.

- vardiff_baseline.md: human-readable summary of the same data,
  organized by metric type for PR review.

Notable findings surfaced by the baseline:

- Convergence: solid across rates (100% at 30+ spm, 95% at 12 spm,
  83% at 6 spm). p50 is ~10 minutes everywhere, dominated by the
  Phase 1 ×3/min ramp clamp.

- Settled accuracy: follows 1/sqrt(N) cleanly. p99 error is 70% at
  6 spm, 27% at 12, 15% at 30, 3% at 60, 0% at 120. Low-rate
  operation is statistically threadbare.

- Steady-state jitter: small everywhere and ~0 above 30 spm. The
  algorithm's growing delta_time post-convergence narrows the
  effective noise band as 1/sqrt(N), producing accidental self-
  stabilization at high rates.

- Reaction sensitivity DEGRADES with share rate — counterintuitive
  but mechanistic. The same property that produces low jitter at
  high rates (growing delta_time after a Phase 1 fire) produces
  sluggish response to step changes (post-step shares diluted by
  long pre-step history). At 60+ spm only 9-16% of trials react to
  a 50% drop within 5 minutes.

This baseline is the reference point for evaluating any future
algorithmic proposal. The regression test in the sim crate asserts
each metric is within tolerance of these recorded values.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Eric Price

sv2/channels-sv2/sim/VARDIFF_SIMULATION_FRAMEWORK.md

@@ -140,7 +140,11 @@ impl Cell {
     /// Stable, machine-readable identifier suitable for use as a key in the
     /// TOML output, in the form `spm_<RATE>.<scenario_key>`.
     pub fn key(&self) -> String {
-        format!("spm_{}.{}", self.shares_per_minute as u32, self.scenario.key())
+        format!(
+            "spm_{}.{}",
+            self.shares_per_minute as u32,
+            self.scenario.key()
+        )
     }
 }
 
@@ -181,12 +185,7 @@ pub struct CellResult {
 
 /// Runs a single cell: builds the scenario, runs `trial_count` trials with
 /// deterministic seeds, computes metric distributions, returns a `CellResult`.
-pub fn run_cell(
-    cell: &Cell,
-    trial_count: usize,
-    base_seed: u64,
-    cell_index: u64,
-) -> CellResult {
+pub fn run_cell(cell: &Cell, trial_count: usize, base_seed: u64, cell_index: u64) -> CellResult {
     let (config, schedule) = cell.scenario.build(cell.shares_per_minute);
 
     let mut trials: Vec<Trial> = Vec::with_capacity(trial_count);
@@ -335,16 +334,56 @@ pub fn serialize_toml(
         ));
         out.push_str(&format!("scenario = \"{}\"\n", result.scenario_key));
         out.push_str(&format!("convergence_rate = {}\n", result.convergence_rate));
-        write_opt(&mut out, "convergence_p10_secs", result.convergence_p10_secs);
-        write_opt(&mut out, "convergence_p50_secs", result.convergence_p50_secs);
-        write_opt(&mut out, "convergence_p90_secs", result.convergence_p90_secs);
-        write_opt(&mut out, "convergence_p95_secs", result.convergence_p95_secs);
-        write_opt(&mut out, "convergence_p99_secs", result.convergence_p99_secs);
-        write_opt(&mut out, "settled_accuracy_p10", result.settled_accuracy_p10);
-        write_opt(&mut out, "settled_accuracy_p50", result.settled_accuracy_p50);
-        write_opt(&mut out, "settled_accuracy_p90", result.settled_accuracy_p90);
-        write_opt(&mut out, "settled_accuracy_p95", result.settled_accuracy_p95);
-        write_opt(&mut out, "settled_accuracy_p99", result.settled_accuracy_p99);
+        write_opt(
+            &mut out,
+            "convergence_p10_secs",
+            result.convergence_p10_secs,
+        );
+        write_opt(
+            &mut out,
+            "convergence_p50_secs",
+            result.convergence_p50_secs,
+        );
+        write_opt(
+            &mut out,
+            "convergence_p90_secs",
+            result.convergence_p90_secs,
+        );
+        write_opt(
+            &mut out,
+            "convergence_p95_secs",
+            result.convergence_p95_secs,
+        );
+        write_opt(
+            &mut out,
+            "convergence_p99_secs",
+            result.convergence_p99_secs,
+        );
+        write_opt(
+            &mut out,
+            "settled_accuracy_p10",
+            result.settled_accuracy_p10,
+        );
+        write_opt(
+            &mut out,
+            "settled_accuracy_p50",
+            result.settled_accuracy_p50,
+        );
+        write_opt(
+            &mut out,
+            "settled_accuracy_p90",
+            result.settled_accuracy_p90,
+        );
+        write_opt(
+            &mut out,
+            "settled_accuracy_p95",
+            result.settled_accuracy_p95,
+        );
+        write_opt(
+            &mut out,
+            "settled_accuracy_p99",
+            result.settled_accuracy_p99,
+        );
         write_opt(&mut out, "jitter_p50_per_min", result.jitter_p50_per_min);
         write_opt(&mut out, "jitter_p90_per_min", result.jitter_p90_per_min);
         write_opt(&mut out, "jitter_p95_per_min", result.jitter_p95_per_min);
@@ -513,16 +552,17 @@ pub fn serialize_markdown(
 }
 
 fn unique_rates(results: &[CellResult]) -> Vec<u32> {
-    let mut rates: Vec<u32> = results
-        .iter()
-        .map(|r| r.shares_per_minute as u32)
-        .collect();
+    let mut rates: Vec<u32> = results.iter().map(|r| r.shares_per_minute as u32).collect();
     rates.sort_unstable();
     rates.dedup();
     rates
 }
 
-fn find_cell<'a>(results: &'a [CellResult], spm: u32, scenario_key: &str) -> Option<&'a CellResult> {
+fn find_cell<'a>(
+    results: &'a [CellResult],
+    spm: u32,
+    scenario_key: &str,
+) -> Option<&'a CellResult> {
     results
         .iter()
         .find(|r| r.shares_per_minute as u32 == spm && r.scenario_key == scenario_key)

sv2/channels-sv2/sim/src/baseline.rs

@@ -32,8 +32,8 @@ use std::path::PathBuf;
 use std::time::Instant;
 
 use vardiff_sim::baseline::{
-    default_cells, run_baseline, serialize_markdown, serialize_toml,
-    DEFAULT_BASELINE_SEED, DEFAULT_TRIAL_COUNT,
+    default_cells, run_baseline, serialize_markdown, serialize_toml, DEFAULT_BASELINE_SEED,
+    DEFAULT_TRIAL_COUNT,
 };
 
 fn main() -> std::io::Result<()> {

sv2/channels-sv2/sim/src/bin/generate-baseline.rs

@@ -193,7 +193,10 @@ pub fn settled_accuracy_for_trial(trial: &Trial) -> Option<f64> {
 /// Distribution of settled accuracy errors across a set of trials. Trials with
 /// non-positive true hashrate are silently dropped.
 pub fn settled_accuracy_distribution(trials: &[Trial]) -> Distribution {
-    let values: Vec<f64> = trials.iter().filter_map(settled_accuracy_for_trial).collect();
+    let values: Vec<f64> = trials
+        .iter()
+        .filter_map(settled_accuracy_for_trial)
+        .collect();
     Distribution::new(values)
 }
 
@@ -247,7 +250,14 @@ pub fn jitter_distribution(
 ) -> Distribution {
     let values: Vec<f64> = trials
         .iter()
-        .filter_map(|t| jitter_for_trial(t, quiet_window_secs, settle_buffer_secs, min_settled_window_secs))
+        .filter_map(|t| {
+            jitter_for_trial(
+                t,
+                quiet_window_secs,
+                settle_buffer_secs,
+                min_settled_window_secs,
+            )
+        })
         .collect();
     Distribution::new(values)
 }
@@ -270,8 +280,10 @@ pub fn reaction_time_for_trial(
     react_window_secs: u64,
 ) -> Option<u64> {
     let window_end = event_at_secs.saturating_add(react_window_secs);
-    let first_post_event_fire: Option<&FireEvent> =
-        trial.fires.iter().find(|f| f.at_secs > event_at_secs && f.at_secs <= window_end);
+    let first_post_event_fire: Option<&FireEvent> = trial
+        .fires
+        .iter()
+        .find(|f| f.at_secs > event_at_secs && f.at_secs <= window_end);
     first_post_event_fire.map(|f| f.at_secs - event_at_secs)
 }
 
@@ -311,11 +323,7 @@ pub fn reaction_time_distribution(
 /// Identical to the `reaction_rate` component of [`reaction_time_distribution`];
 /// kept as a separate function because it's the metric the baseline tables
 /// report and the assertion policy operates on.
-pub fn reaction_sensitivity(
-    trials: &[Trial],
-    event_at_secs: u64,
-    react_window_secs: u64,
-) -> f64 {
+pub fn reaction_sensitivity(trials: &[Trial], event_at_secs: u64, react_window_secs: u64) -> f64 {
     let (rate, _) = reaction_time_distribution(trials, event_at_secs, react_window_secs);
     rate
 }

sv2/channels-sv2/sim/src/metrics.rs

@@ -138,9 +138,8 @@ pub fn parse_baseline_toml(input: &str) -> Result<BaselineDoc, ParseError> {
             .split_once('=')
             .ok_or_else(|| ParseError::MalformedLine(line_no + 1, line.to_string()))?;
         let key = key.trim().to_string();
-        let value = parse_value(raw_value.trim()).ok_or_else(|| {
-            ParseError::MalformedValue(line_no + 1, raw_value.trim().to_string())
-        })?;
+        let value = parse_value(raw_value.trim())
+            .ok_or_else(|| ParseError::MalformedValue(line_no + 1, raw_value.trim().to_string()))?;
         match current_section.as_deref() {
             Some("meta") => {
                 meta_kv.insert(key, value);
@@ -490,7 +489,10 @@ fn compare_max_mul(
                     metric: metric.to_string(),
                     baseline: b,
                     current: c,
-                    tolerance: format!("{} (baseline was 0; current must be ≤ 0.01)", tolerance_desc),
+                    tolerance: format!(
+                        "{} (baseline was 0; current must be ≤ 0.01)",
+                        tolerance_desc
+                    ),
                 });
             }
             return;
@@ -700,7 +702,10 @@ convergence_rate = 0.95
         if !report.is_clean() {
             let mut msg = String::new();
             if !report.failures.is_empty() {
-                msg.push_str(&format!("\n{} tolerance failures:\n", report.failures.len()));
+                msg.push_str(&format!(
+                    "\n{} tolerance failures:\n",
+                    report.failures.len()
+                ));
                 for d in &report.failures {
                     msg.push_str(&format!("  {}\n", d));
                 }

sv2/channels-sv2/sim/src/regression.rs

@@ -25,7 +25,11 @@ impl XorShift64 {
     /// a non-zero constant since XorShift cannot have a zero state.
     pub fn new(seed: u64) -> Self {
         Self {
-            state: if seed == 0 { 0xDEAD_BEEF_CAFE_F00D } else { seed },
+            state: if seed == 0 {
+                0xDEAD_BEEF_CAFE_F00D
+            } else {
+                seed
+            },
         }
     }
 
@@ -46,8 +50,8 @@ impl XorShift64 {
     pub fn next_f64(&mut self) -> f64 {
         // Take 53 bits of randomness (f64 mantissa precision).
         let bits = self.next_u64() >> 11; // 53 bits, range [0, 2^53)
-        // Map [0, 2^53) → (0, 1): add 1 to numerator to exclude 0, divide by
-        // (2^53 + 1) to keep result strictly < 1.
+                                          // Map [0, 2^53) → (0, 1): add 1 to numerator to exclude 0, divide by
+                                          // (2^53 + 1) to keep result strictly < 1.
         ((bits as f64) + 1.0) / ((1u64 << 53) as f64 + 1.0)
     }
 }
@@ -167,7 +171,10 @@ mod tests {
         let mut rng = XorShift64::new(7);
         let rate = 0.5; // Exp(0.5) has mean 2.0
         let n = 100_000;
-        let mean: f64 = (0..n).map(|_| sample_exponential(&mut rng, rate)).sum::<f64>() / n as f64;
+        let mean: f64 = (0..n)
+            .map(|_| sample_exponential(&mut rng, rate))
+            .sum::<f64>()
+            / n as f64;
         // Standard error of mean for Exp(0.5) over n samples is 2 / sqrt(n) ≈ 0.0063.
         // 6-sigma envelope is ±0.04 — very forgiving.
         assert!(
@@ -213,7 +220,9 @@ mod tests {
         // Normal-approximation path: λ = 1000.0
         let mut rng = XorShift64::new(42);
         let n = 10_000;
-        let sum: u64 = (0..n).map(|_| sample_poisson(&mut rng, 1000.0) as u64).sum();
+        let sum: u64 = (0..n)
+            .map(|_| sample_poisson(&mut rng, 1000.0) as u64)
+            .sum();
         let mean = sum as f64 / n as f64;
         // SE of mean for Poisson(1000) over n=10k samples is sqrt(1000/10000) ≈ 0.32.
         // 5-sigma envelope is ±1.6.

sv2/channels-sv2/sim/src/rng.rs

@@ -139,8 +139,7 @@ pub fn run_trial<V: Vardiff>(
 
     let mut rng = XorShift64::new(seed);
     let mut current_hashrate = config.initial_hashrate;
-    let mut current_target =
-        hashrate_to_target_safe(current_hashrate, config.shares_per_minute);
+    let mut current_target = hashrate_to_target_safe(current_hashrate, config.shares_per_minute);
     let mut fires: Vec<FireEvent> = Vec::new();
 
     let mut last_tick_at: u64 = 0;
@@ -200,8 +199,11 @@ pub fn run_trial<V: Vardiff>(
 /// realistic trials. Share rate is floored at 0.001 spm to prevent division
 /// by zero in the underlying conversion.
 fn hashrate_to_target_safe(hashrate: f32, shares_per_minute: f32) -> Target {
-    hash_rate_to_target(hashrate.max(1.0) as f64, shares_per_minute.max(0.001) as f64)
-        .expect("hash_rate_to_target with positive inputs should not fail")
+    hash_rate_to_target(
+        hashrate.max(1.0) as f64,
+        shares_per_minute.max(0.001) as f64,
+    )
+    .expect("hash_rate_to_target with positive inputs should not fail")
 }
 
 #[cfg(test)]
@@ -263,7 +265,10 @@ mod tests {
                 .iter()
                 .zip(t2.fires.iter())
                 .all(|(a, b)| a.at_secs == b.at_secs);
-        assert!(!same, "Two seeds produced identical fire timelines; RNG broken?");
+        assert!(
+            !same,
+            "Two seeds produced identical fire timelines; RNG broken?"
+        );
     }
 
     #[test]
@@ -278,11 +283,7 @@ mod tests {
         // Halve hashrate at 15 min — algorithm should respond.
         let schedule = HashrateSchedule::step(1.0e15, 5.0e14, 15 * 60);
         let trial = run_trial(vardiff, clock, config, &schedule, 9001);
-        let post_step_fires = trial
-            .fires
-            .iter()
-            .filter(|f| f.at_secs > 15 * 60)
-            .count();
+        let post_step_fires = trial.fires.iter().filter(|f| f.at_secs > 15 * 60).count();
         assert!(
             post_step_fires >= 1,
             "Expected at least one fire after 50% load drop at 15 min; got {} post-step fires (total {})",

sv2/channels-sv2/sim/src/trial.rs

@@ -0,0 +1,61 @@
+# Vardiff baseline characterization — `VardiffState`
+
+*Generated by `cargo run --release --bin generate-baseline` from the vardiff_sim crate. 1000 trials per cell, base seed `0xdeadbeefcafef00d`.*
+
+## Convergence time (cold start: 10 GH/s → 1 PH/s)
+
+| share/min | rate | p10 | p50 | p90 | p99 |
+| --- | --- | --- | --- | --- | --- |
+| 6 | 83.3% | 10m | 12m | 21m | 25m |
+| 12 | 95.4% | 10m | 10m | 20m | 25m |
+| 30 | 99.5% | 10m | 10m | 15m | 25m |
+| 60 | 100.0% | 10m | 10m | 10m | 20m |
+| 120 | 100.0% | 10m | 10m | 10m | 15m |
+
+## Settled accuracy (stable load, post-convergence)
+
+`|final_hashrate / true_hashrate - 1|` at trial end. Smaller is better.
+
+| share/min | p10 | p50 | p90 | p99 |
+| --- | --- | --- | --- | --- |
+| 6 | 0.0% | 4.9% | 23.6% | 70.3% |
+| 12 | 0.0% | 0.0% | 12.3% | 26.9% |
+| 30 | 0.0% | 0.0% | 0.8% | 15.6% |
+| 60 | 0.0% | 0.0% | 0.0% | 3.1% |
+| 120 | 0.0% | 0.0% | 0.0% | 0.0% |
+
+## Steady-state jitter (fires per minute)
+
+Post-convergence rate of vardiff fires. Smaller is better — ideal is zero under stable load.
+
+| share/min | p50 | p90 | p99 | mean |
+| --- | --- | --- | --- | --- |
+| 6 | 0.000 | 0.200 | 0.385 | 0.059 |
+| 12 | 0.000 | 0.077 | 0.217 | 0.019 |
+| 30 | 0.000 | 0.000 | 0.067 | 0.002 |
+| 60 | 0.000 | 0.000 | 0.000 | 0.000 |
+| 120 | 0.000 | 0.000 | 0.000 | 0.000 |
+
+## Reaction time to a 50% drop (step at 15 min)
+
+| share/min | reacted | p10 | p50 | p90 | p99 |
+| --- | --- | --- | --- | --- | --- |
+| 6 | 69.7% | 1m | 3m | 5m | 5m |
+| 12 | 54.8% | 1m | 3m | 5m | 5m |
+| 30 | 32.6% | 2m | 4m | 5m | 5m |
+| 60 | 16.3% | 3m | 5m | 5m | 5m |
+| 120 | 8.6% | 4m | 5m | 5m | 5m |
+
+## Reaction sensitivity (P[fire within 5 min of step change])
+
+| Δ% | 6 | 12 | 30 | 60 | 120 |
+| --- | --- | --- | --- | --- | --- |
+| -50% | 0.70 | 0.55 | 0.33 | 0.16 | 0.09 |
+| -25% | 0.44 | 0.23 | 0.08 | 0.00 | 0.00 |
+| -10% | 0.39 | 0.15 | 0.02 | 0.00 | 0.00 |
+| -5% | 0.40 | 0.15 | 0.02 | 0.00 | 0.00 |
+| +5% | 0.39 | 0.13 | 0.02 | 0.00 | 0.00 |
+| +10% | 0.42 | 0.17 | 0.03 | 0.00 | 0.00 |
+| +25% | 0.48 | 0.23 | 0.07 | 0.01 | 0.00 |
+| +50% | 0.64 | 0.47 | 0.32 | 0.22 | 0.29 |
+