ruvector-nervous-system 2.0.6

//! # Circadian Controller: Time-Aware Compute Regulation
//!
//! Implements suprachiasmatic nucleus (SCN) inspired temporal gating for cost reduction.
//!
//! ## Key Cost Benefits
//!
//! 1. **Duty cycle reduction**: 5-50x compute savings through phase-aligned bursts
//! 2. **Gated learning**: 3-10x reduction in write amplification
//! 3. **Error cascade prevention**: Temporal smoothing reduces rollbacks
//! 4. **Hardware efficiency**: Predictable peaks enable smaller clusters
//!
//! ## Philosophy
//!
//! > Time awareness is not about intelligence. It is about restraint.
//! > And restraint is where almost all real-world AI costs are hiding.
//!
//! ## Example
//!
//! ```rust
//! use ruvector_nervous_system::routing::CircadianController;
//!
//! // Create controller with 24-hour simulated cycle
//! let mut clock = CircadianController::new(24.0);
//!
//! // Advance time and check phases
//! clock.advance(6.0); // Simulated 6 hours
//!
//! // Check if expensive operations are permitted
//! if clock.should_compute() {
//!     // Run active computation
//! }
//!
//! if clock.should_learn() {
//!     // Gradient updates, memory writes
//! }
//!
//! if clock.should_consolidate() {
//!     // Background consolidation, garbage collection
//! }
//! ```

use serde::{Deserialize, Serialize};
use std::f32::consts::TAU;

/// Phase states in the circadian cycle
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum CircadianPhase {
    /// Active phase: high compute, fast learning
    Active,
    /// Transition: winding down, consolidation permitted
    Dusk,
    /// Rest phase: minimal compute, background consolidation only
    Rest,
    /// Transition: warming up, preparing for activity
    Dawn,
}

impl CircadianPhase {
    /// Get duty cycle multiplier (0.0 to 1.0)
    pub fn duty_factor(&self) -> f32 {
        match self {
            CircadianPhase::Active => 1.0,
            CircadianPhase::Dawn => 0.5,
            CircadianPhase::Dusk => 0.3,
            CircadianPhase::Rest => 0.05,
        }
    }

    /// Whether learning/writes are permitted
    pub fn allows_learning(&self) -> bool {
        matches!(self, CircadianPhase::Active | CircadianPhase::Dawn)
    }

    /// Whether consolidation operations should run
    pub fn allows_consolidation(&self) -> bool {
        matches!(self, CircadianPhase::Rest | CircadianPhase::Dusk)
    }
}

/// Phase modulation signal for deterministic velocity nudging
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub struct PhaseModulation {
    /// Velocity multiplier (1.0 = normal, >1 = faster, <1 = slower)
    pub velocity: f32,
    /// Direct phase offset (radians, applied once)
    pub offset: f32,
}

impl PhaseModulation {
    /// No modulation (neutral)
    pub fn neutral() -> Self {
        Self {
            velocity: 1.0,
            offset: 0.0,
        }
    }

    /// Speed up phase progression
    pub fn accelerate(factor: f32) -> Self {
        Self {
            velocity: factor.max(0.1),
            offset: 0.0,
        }
    }

    /// Slow down phase progression
    pub fn decelerate(factor: f32) -> Self {
        Self {
            velocity: (1.0 / factor.max(0.1)).min(10.0),
            offset: 0.0,
        }
    }

    /// Nudge phase forward by offset radians
    pub fn nudge_forward(radians: f32) -> Self {
        Self {
            velocity: 1.0,
            offset: radians,
        }
    }
}

/// Circadian controller for temporal gating of compute resources
///
/// Implements a simple but effective phase-based scheduler that reduces costs
/// by enforcing rhythmic activation patterns.
///
/// # Cost Impact
///
/// - **5-50x** reduction in always-on compute costs
/// - **3-10x** reduction in write amplification
/// - Predictable peak loads enable smaller cluster sizing
///
/// # Production Features
///
/// - **Phase modulation**: External signals (coherence, error rate) can nudge phase velocity
/// - **Monotonic decisions**: Once a window opens, it stays open until next phase boundary
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CircadianController {
    /// Current phase in radians (0 to 2π)
    phase: f32,

    /// Period of one full cycle (in arbitrary time units)
    period: f32,

    /// Current phase state
    state: CircadianPhase,

    /// Light/activity signal for entrainment (0.0 to 1.0)
    light_signal: f32,

    /// Phase shift accumulated from entrainment
    phase_shift: f32,

    /// Coherence signal from external sources (gates reactivity)
    coherence: f32,

    /// Total time elapsed
    elapsed: f64,

    /// Activity counter during current phase
    activity_count: u64,

    /// Time since last phase transition
    time_in_phase: f32,

    /// Phase boundaries (in radians)
    dawn_start: f32,
    active_start: f32,
    dusk_start: f32,
    rest_start: f32,

    // === Production Features ===
    /// External phase modulation (coherence, error signals)
    modulation: PhaseModulation,

    /// Latched decisions within phase (monotonic: no flapping)
    compute_latch: Option<bool>,
    learn_latch: Option<bool>,
    consolidate_latch: Option<bool>,
}

impl CircadianController {
    /// Create a new circadian controller
    ///
    /// # Arguments
    ///
    /// * `period` - Duration of one full cycle (e.g., 24.0 for hours, 86400.0 for seconds)
    ///
    /// # Example
    ///
    /// ```rust
    /// use ruvector_nervous_system::routing::CircadianController;
    ///
    /// // 24-hour cycle
    /// let clock = CircadianController::new(24.0);
    /// ```
    pub fn new(period: f32) -> Self {
        // Default phase boundaries: 6h dawn, 6h active, 4h dusk, 8h rest (for 24h cycle)
        // Dawn:   6-8   (2h)  -> 0.25π to 0.33π
        // Active: 8-18  (10h) -> 0.33π to 0.75π
        // Dusk:   18-22 (4h)  -> 0.75π to 0.92π
        // Rest:   22-6  (8h)  -> 0.92π to 0.25π (next day)
        Self {
            phase: 0.0,
            period,
            state: CircadianPhase::Rest,
            light_signal: 0.0,
            phase_shift: 0.0,
            coherence: 0.5,
            elapsed: 0.0,
            activity_count: 0,
            time_in_phase: 0.0,
            // Phase boundaries in radians (0 to 2π)
            dawn_start: 0.25 * TAU,   // 6:00
            active_start: 0.33 * TAU, // 8:00
            dusk_start: 0.75 * TAU,   // 18:00
            rest_start: 0.92 * TAU,   // 22:00
            // Production features
            modulation: PhaseModulation::neutral(),
            compute_latch: None,
            learn_latch: None,
            consolidate_latch: None,
        }
    }

    /// Create controller optimized for high-frequency compute (shorter cycle)
    ///
    /// # Example
    ///
    /// ```rust
    /// use ruvector_nervous_system::routing::CircadianController;
    ///
    /// // 1-second micro-cycle for real-time systems
    /// let clock = CircadianController::fast_cycle(1.0);
    /// assert!(clock.period() == 1.0);
    /// ```
    pub fn fast_cycle(period: f32) -> Self {
        let mut ctrl = Self::new(period);
        // For fast cycles: 20% dawn, 40% active, 15% dusk, 25% rest
        ctrl.dawn_start = 0.0;
        ctrl.active_start = 0.2 * TAU;
        ctrl.dusk_start = 0.6 * TAU;
        ctrl.rest_start = 0.75 * TAU;
        ctrl
    }

    /// Advance the clock by a time delta
    ///
    /// # Arguments
    ///
    /// * `dt` - Time step in the same units as period
    ///
    /// # Example
    ///
    /// ```rust
    /// use ruvector_nervous_system::routing::{CircadianController, CircadianPhase};
    ///
    /// let mut clock = CircadianController::new(24.0);
    /// clock.advance(12.0); // Advance 12 hours
    /// ```
    pub fn advance(&mut self, dt: f32) {
        // Apply entrainment: light shifts phase forward, darkness shifts back
        let entrainment_rate = 0.1 * dt / self.period;
        if self.light_signal > 0.5 {
            // Morning light advances clock
            self.phase_shift += entrainment_rate * (self.light_signal - 0.5);
        }

        // Apply phase modulation (deterministic external signals)
        let velocity = self.modulation.velocity.clamp(0.1, 10.0);
        let offset = self.modulation.offset;
        self.modulation.offset = 0.0; // One-shot offset, consumed after use

        // Update phase with wrap-around, applying velocity modulation
        let delta_phase = TAU * dt * velocity / self.period;
        self.phase = (self.phase + delta_phase + self.phase_shift + offset) % TAU;
        if self.phase < 0.0 {
            self.phase += TAU; // Handle negative wrap
        }
        self.phase_shift *= 0.99; // Decay entrainment shift

        self.elapsed += dt as f64;
        self.time_in_phase += dt;

        // Update state based on phase
        let new_state = self.compute_phase_state();
        if new_state != self.state {
            self.state = new_state;
            self.time_in_phase = 0.0;
            self.activity_count = 0;
            // Reset latches on phase transition (monotonic decisions reset at boundary)
            self.compute_latch = None;
            self.learn_latch = None;
            self.consolidate_latch = None;
        }
    }

    /// Compute current phase state from phase angle
    fn compute_phase_state(&self) -> CircadianPhase {
        let p = self.phase;

        // Handle wrap-around for rest phase
        if p >= self.rest_start || p < self.dawn_start {
            CircadianPhase::Rest
        } else if p >= self.dusk_start {
            CircadianPhase::Dusk
        } else if p >= self.active_start {
            CircadianPhase::Active
        } else {
            CircadianPhase::Dawn
        }
    }

    /// Provide light/activity signal for entrainment
    ///
    /// Higher values (> 0.5) advance the clock, lower values delay it.
    ///
    /// # Arguments
    ///
    /// * `intensity` - Light intensity (0.0 to 1.0)
    pub fn receive_light(&mut self, intensity: f32) {
        self.light_signal = intensity.clamp(0.0, 1.0);
    }

    /// Set coherence signal from external sources
    ///
    /// Used to gate reactivity - low coherence = high restraint
    pub fn set_coherence(&mut self, coherence: f32) {
        self.coherence = coherence.clamp(0.0, 1.0);
    }

    /// Apply phase modulation from external signal
    ///
    /// Use this for deterministic nudges from:
    /// - Mincut coherence spikes → accelerate to active phase
    /// - Error rate spikes → decelerate, extend rest
    /// - External sync signals → phase offset alignment
    ///
    /// # Example
    ///
    /// ```rust
    /// use ruvector_nervous_system::routing::{CircadianController, PhaseModulation};
    ///
    /// let mut clock = CircadianController::new(24.0);
    ///
    /// // High coherence detected - speed up towards active phase
    /// clock.modulate(PhaseModulation::accelerate(1.5));
    ///
    /// // Error spike - slow down, stay in rest longer
    /// clock.modulate(PhaseModulation::decelerate(2.0));
    ///
    /// // External sync - nudge phase forward by 0.1 radians
    /// clock.modulate(PhaseModulation::nudge_forward(0.1));
    /// ```
    pub fn modulate(&mut self, modulation: PhaseModulation) {
        self.modulation = modulation;
    }

    /// Get current phase modulation
    pub fn current_modulation(&self) -> PhaseModulation {
        self.modulation
    }

    /// Check if expensive compute is permitted (monotonic within phase)
    ///
    /// Returns true during Active and Dawn phases.
    /// Once true in a phase, stays true until phase boundary (no flapping).
    #[inline]
    pub fn should_compute(&mut self) -> bool {
        if let Some(latched) = self.compute_latch {
            return latched;
        }
        let decision = matches!(self.state, CircadianPhase::Active | CircadianPhase::Dawn);
        self.compute_latch = Some(decision);
        decision
    }

    /// Check if learning/writes are permitted (monotonic within phase)
    ///
    /// Returns true only during high-confidence periods.
    /// Combines phase gating with coherence signal.
    /// Once decided, stays constant until phase boundary.
    #[inline]
    pub fn should_learn(&mut self) -> bool {
        if let Some(latched) = self.learn_latch {
            return latched;
        }
        let decision = self.state.allows_learning() && self.coherence > 0.3;
        self.learn_latch = Some(decision);
        decision
    }

    /// Check if consolidation operations should run (monotonic within phase)
    ///
    /// Returns true during Rest and Dusk phases.
    /// Once decided, stays constant until phase boundary.
    #[inline]
    pub fn should_consolidate(&mut self) -> bool {
        if let Some(latched) = self.consolidate_latch {
            return latched;
        }
        let decision = self.state.allows_consolidation();
        self.consolidate_latch = Some(decision);
        decision
    }

    /// Check decisions without latching (for inspection only)
    #[inline]
    pub fn peek_compute(&self) -> bool {
        self.compute_latch
            .unwrap_or_else(|| matches!(self.state, CircadianPhase::Active | CircadianPhase::Dawn))
    }

    /// Check decisions without latching (for inspection only)
    #[inline]
    pub fn peek_learn(&self) -> bool {
        self.learn_latch
            .unwrap_or_else(|| self.state.allows_learning() && self.coherence > 0.3)
    }

    /// Check if system should react to an event
    ///
    /// Combines phase, coherence, and event importance for gating.
    ///
    /// # Arguments
    ///
    /// * `importance` - Event importance (0.0 to 1.0)
    #[inline]
    pub fn should_react(&self, importance: f32) -> bool {
        let threshold = match self.state {
            CircadianPhase::Active => 0.1, // React to most events
            CircadianPhase::Dawn => 0.3,   // Moderate threshold
            CircadianPhase::Dusk => 0.5,   // Higher threshold
            CircadianPhase::Rest => 0.8,   // Only critical events
        };

        importance > threshold && (self.coherence > 0.3 || importance > 0.9)
    }

    /// Get current duty cycle factor (0.0 to 1.0)
    ///
    /// Use this to scale compute intensity.
    #[inline]
    pub fn duty_factor(&self) -> f32 {
        self.state.duty_factor()
    }

    /// Get current phase state
    #[inline]
    pub fn phase_state(&self) -> CircadianPhase {
        self.state
    }

    /// Get current phase angle in radians
    #[inline]
    pub fn phase_angle(&self) -> f32 {
        self.phase
    }

    /// Get period
    #[inline]
    pub fn period(&self) -> f32 {
        self.period
    }

    /// Get elapsed time
    #[inline]
    pub fn elapsed(&self) -> f64 {
        self.elapsed
    }

    /// Record an activity event (for monitoring)
    #[inline]
    pub fn record_activity(&mut self) {
        self.activity_count += 1;
    }

    /// Get activity count in current phase
    #[inline]
    pub fn activity_count(&self) -> u64 {
        self.activity_count
    }

    /// Get time spent in current phase
    #[inline]
    pub fn time_in_phase(&self) -> f32 {
        self.time_in_phase
    }

    /// Estimate cost savings from current duty cycle
    ///
    /// Returns estimated compute reduction factor (1.0 = no savings, higher = more savings)
    pub fn cost_reduction_factor(&self) -> f32 {
        1.0 / self.duty_factor().max(0.01)
    }

    /// Reset clock to a specific time (0.0 to 1.0 fraction of cycle)
    pub fn reset_to(&mut self, fraction: f32) {
        self.phase = fraction.clamp(0.0, 1.0) * TAU;
        self.state = self.compute_phase_state();
        self.time_in_phase = 0.0;
        self.activity_count = 0;
    }
}

impl Default for CircadianController {
    fn default() -> Self {
        Self::new(24.0)
    }
}

/// Hysteresis tracker for preventing flapping on modulation signals
///
/// Requires N consecutive ticks above threshold before triggering,
/// preventing spurious modulation from noise.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HysteresisTracker {
    /// Current consecutive ticks above threshold
    ticks_above: u32,
    /// Required consecutive ticks to trigger
    required_ticks: u32,
    /// Threshold value
    threshold: f32,
    /// Whether condition is currently triggered
    triggered: bool,
}

impl HysteresisTracker {
    /// Create a new hysteresis tracker
    ///
    /// # Arguments
    ///
    /// * `threshold` - Value that must be exceeded
    /// * `required_ticks` - Consecutive ticks needed before triggering
    pub fn new(threshold: f32, required_ticks: u32) -> Self {
        Self {
            ticks_above: 0,
            required_ticks: required_ticks.max(1),
            threshold,
            triggered: false,
        }
    }

    /// Update tracker with new value, returns true if triggered
    pub fn update(&mut self, value: f32) -> bool {
        if value > self.threshold {
            self.ticks_above = self.ticks_above.saturating_add(1);
            if self.ticks_above >= self.required_ticks {
                self.triggered = true;
            }
        } else {
            self.ticks_above = 0;
            self.triggered = false;
        }
        self.triggered
    }

    /// Check if currently triggered
    pub fn is_triggered(&self) -> bool {
        self.triggered
    }

    /// Reset tracker
    pub fn reset(&mut self) {
        self.ticks_above = 0;
        self.triggered = false;
    }

    /// Get ticks above threshold
    pub fn ticks_above(&self) -> u32 {
        self.ticks_above
    }
}

/// Budget guardrail for automatic deceleration
///
/// Tracks compute spend and forces deceleration when budget is exceeded.
/// Multiplies all duty factors by a reduction factor when overspending.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BudgetGuardrail {
    /// Budget per hour (arbitrary units matching energy tracking)
    budget_per_hour: f64,
    /// Current spend in this hour
    current_spend: f64,
    /// Hours elapsed since last reset
    hours_elapsed: f64,
    /// Reduction factor when overspending (0.0-1.0)
    overspend_reduction: f32,
    /// Whether currently in overspend mode
    overspending: bool,
    /// Spend history for trend analysis (last N hours)
    spend_history: Vec<f64>,
    /// Max history entries
    max_history: usize,
}

impl BudgetGuardrail {
    /// Create a new budget guardrail
    ///
    /// # Arguments
    ///
    /// * `budget_per_hour` - Maximum spend allowed per hour
    /// * `overspend_reduction` - Factor to multiply duty by when overspending (e.g., 0.5)
    pub fn new(budget_per_hour: f64, overspend_reduction: f32) -> Self {
        Self {
            budget_per_hour,
            current_spend: 0.0,
            hours_elapsed: 0.0,
            overspend_reduction: overspend_reduction.clamp(0.0, 1.0),
            overspending: false,
            spend_history: Vec::with_capacity(24),
            max_history: 24,
        }
    }

    /// Record spend and time delta
    pub fn record_spend(&mut self, spend: f64, dt_hours: f64) {
        self.current_spend += spend;
        self.hours_elapsed += dt_hours;

        // Check if hour boundary crossed
        if self.hours_elapsed >= 1.0 {
            // Save to history
            if self.spend_history.len() >= self.max_history {
                self.spend_history.remove(0);
            }
            self.spend_history.push(self.current_spend);

            // Reset for new hour
            self.current_spend = 0.0;
            self.hours_elapsed -= 1.0;
        }

        // Check overspend status
        let projected_spend = self.current_spend / self.hours_elapsed.max(0.001);
        self.overspending = projected_spend > self.budget_per_hour;
    }

    /// Get the duty factor multiplier based on budget status
    ///
    /// Returns 1.0 if within budget, or overspend_reduction if overspending
    pub fn duty_multiplier(&self) -> f32 {
        if self.overspending {
            self.overspend_reduction
        } else {
            1.0
        }
    }

    /// Check if currently overspending
    pub fn is_overspending(&self) -> bool {
        self.overspending
    }

    /// Get current spend rate (spend per hour)
    pub fn current_spend_rate(&self) -> f64 {
        if self.hours_elapsed > 0.0 {
            self.current_spend / self.hours_elapsed
        } else {
            0.0
        }
    }

    /// Get budget utilization (0.0-1.0+)
    pub fn utilization(&self) -> f64 {
        self.current_spend_rate() / self.budget_per_hour
    }

    /// Get average spend from history
    pub fn average_historical_spend(&self) -> f64 {
        if self.spend_history.is_empty() {
            return 0.0;
        }
        self.spend_history.iter().sum::<f64>() / self.spend_history.len() as f64
    }

    /// Reset guardrail
    pub fn reset(&mut self) {
        self.current_spend = 0.0;
        self.hours_elapsed = 0.0;
        self.overspending = false;
        self.spend_history.clear();
    }
}

impl Default for BudgetGuardrail {
    fn default() -> Self {
        Self::new(1000.0, 0.5) // Default: 1000 units/hour, halve duty when overspending
    }
}

/// Nervous system metrics scorecard
///
/// Five concrete metrics for measuring system restraint and efficiency:
/// 1. Silence Ratio: How often the system stays calm
/// 2. Time to Decision: Reflex speed (P50/P95)
/// 3. Energy per Spike: True efficiency normalized across changes
/// 4. Calmness Index: Post-learning stability
/// 5. Write Amplification: Memory writes per meaningful event
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct NervousSystemMetrics {
    /// Total ticks observed
    pub total_ticks: u64,
    /// Active ticks (processing events)
    pub active_ticks: u64,
    /// Total spikes/events processed
    pub total_spikes: u64,
    /// Total energy consumed (arbitrary units)
    pub total_energy: f64,
    /// Baseline spikes per hour (for calmness index)
    pub baseline_spikes_per_hour: f64,
    /// Decision latencies in microseconds (circular buffer)
    decision_latencies: Vec<u64>,
    /// Max latencies to track
    max_latencies: usize,
    /// Total memory writes (inserts + updates)
    pub memory_writes: u64,
    /// Meaningful events (events that changed state)
    pub meaningful_events: u64,
}

impl NervousSystemMetrics {
    /// Create new metrics tracker
    pub fn new(baseline_spikes_per_hour: f64) -> Self {
        Self {
            total_ticks: 0,
            active_ticks: 0,
            total_spikes: 0,
            total_energy: 0.0,
            baseline_spikes_per_hour,
            decision_latencies: Vec::with_capacity(1000),
            max_latencies: 1000,
            memory_writes: 0,
            meaningful_events: 0,
        }
    }

    /// Record a tick (active or idle)
    pub fn record_tick(&mut self, active: bool, spikes: u64, energy: f64) {
        self.total_ticks += 1;
        if active {
            self.active_ticks += 1;
        }
        self.total_spikes += spikes;
        self.total_energy += energy;
    }

    /// Record memory operations for write amplification tracking
    ///
    /// # Arguments
    ///
    /// * `writes` - Number of memory writes (inserts + updates)
    /// * `meaningful` - Whether this was a meaningful event (changed state)
    pub fn record_memory_op(&mut self, writes: u64, meaningful: bool) {
        self.memory_writes += writes;
        if meaningful {
            self.meaningful_events += 1;
        }
    }

    /// Record a decision latency in microseconds
    pub fn record_decision(&mut self, latency_us: u64) {
        if self.decision_latencies.len() >= self.max_latencies {
            self.decision_latencies.remove(0);
        }
        self.decision_latencies.push(latency_us);
    }

    /// Silence Ratio: 1 - (active_ticks / total_ticks)
    /// Higher is better - system stays calm
    pub fn silence_ratio(&self) -> f64 {
        if self.total_ticks == 0 {
            return 1.0;
        }
        1.0 - (self.active_ticks as f64 / self.total_ticks as f64)
    }

    /// Time to Decision P50 (median) in microseconds
    pub fn ttd_p50(&self) -> Option<u64> {
        self.percentile(0.5)
    }

    /// Time to Decision P95 in microseconds
    pub fn ttd_p95(&self) -> Option<u64> {
        self.percentile(0.95)
    }

    fn percentile(&self, p: f64) -> Option<u64> {
        if self.decision_latencies.is_empty() {
            return None;
        }
        let mut sorted = self.decision_latencies.clone();
        sorted.sort_unstable();
        let idx = ((sorted.len() as f64 * p) as usize).min(sorted.len() - 1);
        Some(sorted[idx])
    }

    /// Energy per Spike (nJ/spike equivalent)
    pub fn energy_per_spike(&self) -> f64 {
        if self.total_spikes == 0 {
            return 0.0;
        }
        self.total_energy / self.total_spikes as f64
    }

    /// Calmness Index: exp(-spikes_per_hour / baseline_spikes)
    /// Closer to 1 means stable, settled system
    pub fn calmness_index(&self, hours_elapsed: f64) -> f64 {
        if hours_elapsed <= 0.0 || self.baseline_spikes_per_hour <= 0.0 {
            return 1.0;
        }
        let spikes_per_hour = self.total_spikes as f64 / hours_elapsed;
        (-spikes_per_hour / self.baseline_spikes_per_hour).exp()
    }

    /// Write Amplification Factor: memory_writes / meaningful_events
    ///
    /// Lower is better - fewer redundant writes per real change.
    /// Ideal systems approach 1.0 (one write per meaningful change).
    pub fn write_amplification(&self) -> f64 {
        if self.meaningful_events == 0 {
            return 0.0;
        }
        self.memory_writes as f64 / self.meaningful_events as f64
    }

    /// Check if TTD exceeds budget (for alerting)
    pub fn ttd_exceeds_budget(&self, budget_us: u64) -> bool {
        self.ttd_p95().map(|p95| p95 > budget_us).unwrap_or(false)
    }

    /// Generate a full scorecard report
    pub fn scorecard(&self, hours_elapsed: f64) -> NervousSystemScorecard {
        NervousSystemScorecard {
            silence_ratio: self.silence_ratio(),
            ttd_p50_us: self.ttd_p50(),
            ttd_p95_us: self.ttd_p95(),
            energy_per_spike: self.energy_per_spike(),
            calmness_index: self.calmness_index(hours_elapsed),
            write_amplification: self.write_amplification(),
            total_ticks: self.total_ticks,
            total_spikes: self.total_spikes,
        }
    }

    /// Reset metrics
    pub fn reset(&mut self) {
        self.total_ticks = 0;
        self.active_ticks = 0;
        self.total_spikes = 0;
        self.total_energy = 0.0;
        self.decision_latencies.clear();
        self.memory_writes = 0;
        self.meaningful_events = 0;
    }
}

/// Complete scorecard for nervous system health
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NervousSystemScorecard {
    /// Silence ratio (0.0-1.0, higher = calmer)
    pub silence_ratio: f64,
    /// Time to decision P50 in microseconds
    pub ttd_p50_us: Option<u64>,
    /// Time to decision P95 in microseconds
    pub ttd_p95_us: Option<u64>,
    /// Energy per spike
    pub energy_per_spike: f64,
    /// Calmness index (0.0-1.0, higher = more settled)
    pub calmness_index: f64,
    /// Write amplification factor (lower = better, ideal = 1.0)
    pub write_amplification: f64,
    /// Total ticks observed
    pub total_ticks: u64,
    /// Total spikes processed
    pub total_spikes: u64,
}

impl NervousSystemScorecard {
    /// Check if system is healthy (meeting all targets)
    pub fn is_healthy(&self, targets: &ScorecardTargets) -> bool {
        self.silence_ratio >= targets.min_silence_ratio
            && self
                .ttd_p95_us
                .map(|p95| p95 <= targets.max_ttd_p95_us)
                .unwrap_or(true)
            && self.energy_per_spike <= targets.max_energy_per_spike
            && self.write_amplification <= targets.max_write_amplification
    }

    /// Get health score (0.0-1.0)
    pub fn health_score(&self, targets: &ScorecardTargets) -> f64 {
        let mut score = 0.0;
        let mut count = 0.0;

        // Silence ratio contribution
        score += (self.silence_ratio / targets.min_silence_ratio).min(1.0);
        count += 1.0;

        // TTD contribution (inverted - lower is better)
        if let Some(p95) = self.ttd_p95_us {
            score += (targets.max_ttd_p95_us as f64 / p95 as f64).min(1.0);
            count += 1.0;
        }

        // Energy contribution (inverted - lower is better)
        if self.energy_per_spike > 0.0 {
            score += (targets.max_energy_per_spike / self.energy_per_spike).min(1.0);
            count += 1.0;
        }

        // Write amplification contribution (inverted - lower is better)
        if self.write_amplification > 0.0 {
            score += (targets.max_write_amplification / self.write_amplification).min(1.0);
            count += 1.0;
        }

        // Calmness bonus
        score += self.calmness_index;
        count += 1.0;

        score / count
    }
}

/// Target thresholds for scorecard health checks
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScorecardTargets {
    /// Minimum acceptable silence ratio
    pub min_silence_ratio: f64,
    /// Maximum acceptable TTD P95 in microseconds
    pub max_ttd_p95_us: u64,
    /// Maximum acceptable energy per spike
    pub max_energy_per_spike: f64,
    /// Maximum acceptable write amplification
    pub max_write_amplification: f64,
}

impl Default for ScorecardTargets {
    fn default() -> Self {
        Self {
            min_silence_ratio: 0.7,       // At least 70% quiet
            max_ttd_p95_us: 10_000,       // 10ms max P95
            max_energy_per_spike: 100.0,  // 100 units max
            max_write_amplification: 3.0, // Max 3 writes per meaningful event
        }
    }
}

/// Circadian-gated task scheduler
///
/// Wraps tasks with circadian awareness for automatic duty cycling.
#[derive(Debug, Clone)]
pub struct CircadianScheduler<T> {
    controller: CircadianController,
    /// Pending tasks queued during rest phase
    pending: Vec<T>,
    /// Maximum pending queue size
    max_pending: usize,
}

impl<T> CircadianScheduler<T> {
    /// Create new scheduler with given period
    pub fn new(period: f32, max_pending: usize) -> Self {
        Self {
            controller: CircadianController::new(period),
            pending: Vec::with_capacity(max_pending.min(1000)),
            max_pending,
        }
    }

    /// Submit a task for execution
    ///
    /// Returns true if task was executed immediately, false if queued
    pub fn submit<F>(&mut self, task: T, importance: f32, execute: F) -> bool
    where
        F: FnOnce(T),
    {
        if self.controller.should_react(importance) {
            execute(task);
            self.controller.record_activity();
            true
        } else if self.pending.len() < self.max_pending {
            self.pending.push(task);
            false
        } else {
            // Drop low-priority tasks when queue is full
            false
        }
    }

    /// Advance time and process pending tasks if appropriate
    pub fn advance<F>(&mut self, dt: f32, mut execute: F)
    where
        F: FnMut(T),
    {
        self.controller.advance(dt);

        // Process pending during active phase
        if self.controller.should_compute() && !self.pending.is_empty() {
            let batch_size = (self.pending.len() as f32 * self.controller.duty_factor()) as usize;
            let batch_size = batch_size.max(1).min(self.pending.len());

            for _ in 0..batch_size {
                if let Some(task) = self.pending.pop() {
                    execute(task);
                    self.controller.record_activity();
                }
            }
        }
    }

    /// Get reference to controller
    pub fn controller(&self) -> &CircadianController {
        &self.controller
    }

    /// Get mutable reference to controller
    pub fn controller_mut(&mut self) -> &mut CircadianController {
        &mut self.controller
    }

    /// Get pending task count
    pub fn pending_count(&self) -> usize {
        self.pending.len()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_phase_transitions() {
        let mut clock = CircadianController::new(24.0);

        // Start at midnight (rest phase)
        assert_eq!(clock.phase_state(), CircadianPhase::Rest);

        // Advance to 7am (dawn)
        clock.advance(7.0);
        assert_eq!(clock.phase_state(), CircadianPhase::Dawn);

        // Advance to 10am (active)
        clock.advance(3.0);
        assert_eq!(clock.phase_state(), CircadianPhase::Active);

        // Advance to 7pm (dusk)
        clock.advance(9.0);
        assert_eq!(clock.phase_state(), CircadianPhase::Dusk);

        // Advance to midnight (rest)
        clock.advance(5.0);
        assert_eq!(clock.phase_state(), CircadianPhase::Rest);
    }

    #[test]
    fn test_duty_factors() {
        assert_eq!(CircadianPhase::Active.duty_factor(), 1.0);
        assert_eq!(CircadianPhase::Dawn.duty_factor(), 0.5);
        assert_eq!(CircadianPhase::Dusk.duty_factor(), 0.3);
        assert_eq!(CircadianPhase::Rest.duty_factor(), 0.05);
    }

    #[test]
    fn test_gating_logic() {
        let mut clock = CircadianController::new(24.0);
        clock.set_coherence(0.8);

        // Rest phase: minimal activity
        assert!(!clock.should_compute());
        assert!(!clock.should_learn());
        assert!(clock.should_consolidate());
        assert!(!clock.should_react(0.5));
        assert!(clock.should_react(0.9)); // Critical events always pass

        // Advance to active phase
        clock.advance(10.0);
        assert!(clock.should_compute());
        assert!(clock.should_learn());
        assert!(!clock.should_consolidate());
        assert!(clock.should_react(0.2));
    }

    #[test]
    fn test_entrainment() {
        let mut clock1 = CircadianController::new(24.0);
        let mut clock2 = CircadianController::new(24.0);

        // Clock2 receives morning light
        clock2.receive_light(1.0);

        // Advance both
        for _ in 0..10 {
            clock1.advance(1.0);
            clock2.advance(1.0);
        }

        // Light-exposed clock should be phase-advanced
        assert!(clock2.phase_angle() > clock1.phase_angle());
    }

    #[test]
    fn test_cost_reduction() {
        let mut clock = CircadianController::new(24.0);

        // During rest, cost reduction should be high
        assert!(clock.cost_reduction_factor() > 10.0);

        // During active, minimal reduction
        clock.advance(10.0);
        assert!((clock.cost_reduction_factor() - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_scheduler() {
        let mut scheduler: CircadianScheduler<u32> = CircadianScheduler::new(24.0, 100);
        let mut executed = Vec::new();

        // Submit during rest - should queue
        let immediate = scheduler.submit(1, 0.3, |t| executed.push(t));
        assert!(!immediate);
        assert_eq!(scheduler.pending_count(), 1);

        // Submit critical task - should execute
        let immediate = scheduler.submit(2, 0.95, |t| executed.push(t));
        assert!(immediate);
        assert_eq!(executed, vec![2]);

        // Advance to active phase and process pending
        scheduler.advance(10.0, |t| executed.push(t));
        assert!(executed.contains(&1));
    }

    #[test]
    fn test_fast_cycle() {
        let clock = CircadianController::fast_cycle(1.0);
        assert_eq!(clock.period(), 1.0);

        // Fast cycle should still have all phases
        let mut c = clock.clone();
        let mut phases_seen = std::collections::HashSet::new();
        for i in 0..100 {
            c.advance(0.01);
            phases_seen.insert(c.phase_state());
        }
        assert_eq!(phases_seen.len(), 4);
    }
}