Merge pull request #529 from khalyaro/feat/sandbox-runner-fixtures-scenario-timetravel

Add sandbox runner tests, fixture generators, scenario DSL, and time travel (#480, #479, #478, #477)

Author: Tinna23

packages/devkit/src/analysis/percentile.rs

@@ -94,6 +94,31 @@ pub fn percentile_interpolated(sorted: &[u64], p: u8) -> f64 {
     sorted[lo] as f64 + frac * (sorted[hi] as f64 - sorted[lo] as f64)
 }
 
+/// Nearest-rank percentile of an unsorted slice.
+///
+/// Sorts a copy internally; accepts `f64` percentile values for ergonomics.
+/// Returns 0 for empty slices.
+pub fn percentile_nearest_rank(data: &[u64], p: f64) -> u64 {
+    if data.is_empty() {
+        return 0;
+    }
+    let mut sorted = data.to_vec();
+    sorted.sort_unstable();
+    let p_usize = (p.round() as usize).clamp(1, 100);
+    Percentile::nearest_rank(&sorted, p_usize)
+}
+
+/// Compute a full fee distribution summary for an unsorted slice.
+///
+/// Returns the summary directly; panics only if the slice is empty (callers
+/// should guard with `!data.is_empty()`).
+pub fn fee_distribution_summary(data: &[u64]) -> FeeDistributionSummary {
+    let mut sorted = data.to_vec();
+    sorted.sort_unstable();
+    Percentile::fee_distribution_summary(&sorted)
+        .expect("fee_distribution_summary called on empty data")
+}
+
 // ── P² streaming percentile estimator (Issue #261) ───────────────────────────
 
 /// Streaming percentile estimator using the P² algorithm (Jain & Chlamtac, 1985).

packages/devkit/src/analysis/spike_classifier.rs

@@ -32,9 +32,41 @@ pub struct TimestampedSpikeEvent {
 }
 
 /// Classifies fee spikes in a time series.
-pub struct SpikeClassifier;
+pub struct SpikeClassifier {
+    baseline: u64,
+}
+
+impl Default for SpikeClassifier {
+    fn default() -> Self {
+        Self { baseline: 200 }
+    }
+}
 
 impl SpikeClassifier {
+    /// Create a classifier with the given baseline.
+    pub fn new(baseline: u64) -> Self {
+        Self { baseline }
+    }
+
+    /// Classify a single fee using the configured baseline.
+    ///
+    /// Returns [`SpikeSeverity::Low`] for fees below the 2× spike threshold.
+    pub fn classify(&self, fee: u64) -> SpikeSeverity {
+        if self.baseline == 0 {
+            return SpikeSeverity::Low;
+        }
+        let ratio = fee as f64 / self.baseline as f64;
+        if ratio > 50.0 {
+            SpikeSeverity::Critical
+        } else if ratio >= 10.0 {
+            SpikeSeverity::High
+        } else if ratio >= 5.0 {
+            SpikeSeverity::Medium
+        } else {
+            SpikeSeverity::Low
+        }
+    }
+
     /// Returns indices of fees that fall outside 1.5 × IQR from Q1/Q3.
     /// `fees` need not be sorted; indices refer to the original slice.
     pub fn iqr_outliers(fees: &[u64]) -> Vec<usize> {
@@ -57,7 +89,7 @@ impl SpikeClassifier {
 
     /// Classify a single fee against a baseline.
     /// Returns `None` if the fee is below the 2× spike threshold.
-    pub fn classify(fee: u64, baseline: u64) -> Option<SpikeSeverity> {
+    pub fn classify_with_baseline(fee: u64, baseline: u64) -> Option<SpikeSeverity> {
         if baseline == 0 {
             return None;
         }
@@ -77,14 +109,14 @@ impl SpikeClassifier {
         let mut events = Vec::new();
         let mut i = 0;
         while i < fees.len() {
-            if let Some(severity) = Self::classify(fees[i], baseline) {
+            if let Some(severity) = Self::classify_with_baseline(fees[i], baseline) {
                 let start = i;
-                while i < fees.len() && Self::classify(fees[i], baseline).is_some() {
+                while i < fees.len() && Self::classify_with_baseline(fees[i], baseline).is_some() {
                     i += 1;
                 }
                 let severity = fees[start..i]
                     .iter()
-                    .filter_map(|&f| Self::classify(f, baseline))
+                    .filter_map(|&f| Self::classify_with_baseline(f, baseline))
                     .max_by_key(|s| match s {
                         SpikeSeverity::Low => 1,
                         SpikeSeverity::Medium => 2,

packages/devkit/src/lib.rs

@@ -6,6 +6,7 @@ pub mod data_quality;
 pub mod error;
 pub mod harness;
 pub mod monitoring;
+pub mod resilience;
 pub mod sandbox;
 pub mod simulation;
 pub mod test_helpers;

packages/devkit/src/sandbox/fixtures.rs

@@ -30,6 +30,46 @@ pub fn normal_network() -> Vec<(u64, u64)> {
         .collect()
 }
 
+/// Generates 10,000 fee records representing a congested Stellar testnet session.
+///
+/// Fees are clustered in the **10,000–80,000 stroop** range with linearly
+/// increasing variation. Timestamps are spaced ~8.64 seconds apart spanning
+/// exactly 24 hours.
+pub fn congested_network() -> Vec<(u64, u64)> {
+    const ANCHOR_MS: u64 = 1_753_315_200_000;
+    const COUNT: usize = 10_000;
+    const DAY_MS: u64 = 86_400_000;
+    let interval_ms = DAY_MS / COUNT as u64;
+
+    (0..COUNT)
+        .map(|i| {
+            let timestamp_ms = ANCHOR_MS + i as u64 * interval_ms;
+            let fee = 10_000 + (i as u64 * 70_000 / COUNT as u64);
+            (timestamp_ms, fee)
+        })
+        .collect()
+}
+
+/// Generates 10,000 fee records representing a volatile Stellar network.
+///
+/// Most fees are very low (~10 stroops), but ~10% spike to ~80,000, producing
+/// a high coefficient of variation. Timestamps are spaced ~8.64 seconds apart
+/// spanning 24 hours.
+pub fn volatile_network() -> Vec<(u64, u64)> {
+    const ANCHOR_MS: u64 = 1_753_315_200_000;
+    const COUNT: usize = 10_000;
+    const DAY_MS: u64 = 86_400_000;
+    let interval_ms = DAY_MS / COUNT as u64;
+
+    (0..COUNT)
+        .map(|i| {
+            let timestamp_ms = ANCHOR_MS + i as u64 * interval_ms;
+            let fee = if i % 10 == 0 { 80_000 } else { 10 };
+            (timestamp_ms, fee)
+        })
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -53,4 +93,21 @@ mod tests {
             assert!(w[0].0 < w[1].0);
         }
     }
+
+    #[test]
+    fn congested_network_count() {
+        assert_eq!(congested_network().len(), 10_000);
+    }
+
+    #[test]
+    fn congested_network_fees_in_range() {
+        for (_, fee) in congested_network() {
+            assert!(fee >= 10_000 && fee <= 80_000, "fee out of range: {fee}");
+        }
+    }
+
+    #[test]
+    fn volatile_network_count() {
+        assert_eq!(volatile_network().len(), 10_000);
+    }
 }

packages/devkit/src/sandbox/mod.rs

@@ -1,3 +1,4 @@
 pub mod environment;
 pub mod fixtures;
 pub mod runner;
+pub mod scenario;

packages/devkit/src/sandbox/runner.rs

@@ -1,5 +1,7 @@
 //! Synchronous test runner for the sandbox environment.
 
+use std::time::Duration as StdDuration;
+
 use crate::sandbox::environment::SandboxEnv;
 
 /// Runs `f` with a freshly-seeded [`SandboxEnv`] and returns its result.
@@ -11,6 +13,43 @@ where
     f(&env)
 }
 
+/// Collects timing and record-count metadata for a sandbox run.
+pub struct ResultCollector {
+    duration: StdDuration,
+    records_processed: usize,
+}
+
+impl ResultCollector {
+    pub fn new() -> Self {
+        Self {
+            duration: StdDuration::ZERO,
+            records_processed: 0,
+        }
+    }
+
+    pub fn record_duration(&mut self, d: StdDuration) {
+        self.duration = d;
+    }
+
+    pub fn duration(&self) -> StdDuration {
+        self.duration
+    }
+
+    pub fn set_records_processed(&mut self, n: usize) {
+        self.records_processed = n;
+    }
+
+    pub fn records_processed(&self) -> usize {
+        self.records_processed
+    }
+}
+
+impl Default for ResultCollector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

packages/devkit/src/sandbox/scenario.rs

@@ -0,0 +1,76 @@
+//! Scenario DSL for composing sandbox test configurations.
+//!
+//! Provides a builder-pattern API for constructing [`Scenario`]s that
+//! describe fixture type, duration, and optional spike injections.
+
+use chrono::Duration;
+
+/// Network fixture type for a scenario.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Fixture {
+    Normal,
+    Congested,
+    Spike,
+}
+
+/// A fully-resolved sandbox scenario configuration.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Scenario {
+    pub fixture: Fixture,
+    pub duration: Duration,
+    pub spike_at: Option<(i64, u64)>,
+}
+
+impl Scenario {
+    /// Start building a new [`Scenario`].
+    pub fn builder() -> ScenarioBuilder {
+        ScenarioBuilder::default()
+    }
+}
+
+/// Builder for constructing a [`Scenario`] step by step.
+#[derive(Debug, Clone)]
+pub struct ScenarioBuilder {
+    fixture: Fixture,
+    duration: Duration,
+    spike_at: Option<(i64, u64)>,
+}
+
+impl Default for ScenarioBuilder {
+    fn default() -> Self {
+        Self {
+            fixture: Fixture::Normal,
+            duration: Duration::hours(1),
+            spike_at: None,
+        }
+    }
+}
+
+impl ScenarioBuilder {
+    /// Set the network fixture for the scenario.
+    pub fn fixture(mut self, fixture: Fixture) -> Self {
+        self.fixture = fixture;
+        self
+    }
+
+    /// Set the total duration of the scenario.
+    pub fn duration(mut self, duration: Duration) -> Self {
+        self.duration = duration;
+        self
+    }
+
+    /// Inject a spike at the given offset (seconds) with the given fee (stroops).
+    pub fn inject_spike_at(mut self, offset_secs: i64, fee_stroops: u64) -> Self {
+        self.spike_at = Some((offset_secs, fee_stroops));
+        self
+    }
+
+    /// Consume the builder and produce a [`Scenario`].
+    pub fn build(self) -> Scenario {
+        Scenario {
+            fixture: self.fixture,
+            duration: self.duration,
+            spike_at: self.spike_at,
+        }
+    }
+}

packages/devkit/tests/sandbox_fixtures.rs

@@ -0,0 +1,43 @@
+use stellar_devkit::analysis::percentile::percentile_nearest;
+use stellar_devkit::sandbox::fixtures::*;
+
+#[test]
+fn test_normal_fixture_has_no_spikes() {
+    let fees = normal_network();
+    assert!(!fees.is_empty());
+
+    let mut values: Vec<u64> = fees.iter().map(|(_, f)| *f).collect();
+    values.sort();
+    let p95 = percentile_nearest(&values, 95);
+
+    // Normal fixture should have reasonable p95 (below 50,000 stroops)
+    assert!(p95 < 50_000, "Normal fixture p95 {} should be below 50,000", p95);
+}
+
+#[test]
+fn test_congested_fixture_high_fees() {
+    let fees = congested_network();
+    assert!(!fees.is_empty());
+
+    let mut values: Vec<u64> = fees.iter().map(|(_, f)| *f).collect();
+    values.sort();
+    let p95 = percentile_nearest(&values, 95);
+
+    // Congested fixture should have p95 > 50,000
+    assert!(p95 > 50_000, "Congested fixture p95 {} should be above 50,000", p95);
+}
+
+#[test]
+fn test_volatile_fixture_high_cv() {
+    let fees = volatile_network();
+    assert!(!fees.is_empty());
+
+    let values: Vec<u64> = fees.iter().map(|(_, f)| *f).collect();
+    let mean = values.iter().sum::<u64>() as f64 / values.len() as f64;
+    let variance = values.iter().map(|v| (*v as f64 - mean).powi(2)).sum::<f64>() / values.len() as f64;
+    let std_dev = variance.sqrt();
+    let cv = std_dev / mean;
+
+    // Volatile fixture should have CV > 2.0
+    assert!(cv > 2.0, "Volatile fixture CV {} should be above 2.0", cv);
+}

packages/devkit/tests/sandbox_runner.rs

@@ -0,0 +1,38 @@
+use stellar_devkit::sandbox::runner::*;
+use std::time::Instant;
+
+#[test]
+fn test_runner_executes_closure() {
+    let mut executed = false;
+    run(|_env| {
+        executed = true;
+    });
+    assert!(executed, "Runner should execute the closure");
+}
+
+#[test]
+fn test_runner_provides_non_empty_env() {
+    run(|env| {
+        let records = env.records();
+        assert!(!records.is_empty(), "Sandbox env should have records");
+    });
+}
+
+#[test]
+fn test_result_collector_captures_duration() {
+    let start = Instant::now();
+    let mut collector = ResultCollector::new();
+
+    // Simulate some work
+    std::thread::sleep(std::time::Duration::from_millis(10));
+
+    collector.record_duration(start.elapsed());
+    assert!(collector.duration().as_millis() >= 10, "Should capture duration");
+}
+
+#[test]
+fn test_result_collector_captures_record_count() {
+    let mut collector = ResultCollector::new();
+    collector.set_records_processed(100);
+    assert_eq!(collector.records_processed(), 100);
+}