homeostatic-tune

name: homeostatic-tune description: Configure and monitor homeostatic control in the Sphere-Vortex Framework. Use when adjusting system targets, tuning adaptation rates, analyzing deviations from equilibrium, or implementing feedback control. Covers M16 (homeostatic.rs) and integration with learning/vortex systems.

Homeostatic Tuning

This skill provides expertise for homeostatic control and adaptive feedback in the Sphere-Vortex Framework (M16 - src/learning/homeostatic.rs).

Quick Reference

Target Parameters

Feedback Modes

enum FeedbackMode {
    Proportional,   // Direct error correction
    Integral,       // Accumulated error
    Derivative,     // Rate of change
    PID,            // Full PID control
}

Deviation Thresholds

• < 0.05: Within tolerance (no action)
• 0.05-0.10: Minor adjustment needed
• 0.10-0.20: Significant deviation
• > 0.20: Critical - immediate correction

When to Use This Skill

1. Setting system targets for relevance, coherence, synergy
2. Monitoring deviations from equilibrium
3. Tuning adaptation rates for stability
4. Implementing feedback loops across modules
5. Diagnosing oscillation or instability

Tier 1: Quick Operations

Check Current State

let state = controller.get_state();
println!("Relevance: {:.3} (target: {:.3}, Δ: {:.3})",
    state.current_relevance,
    state.target_relevance,
    state.current_relevance - state.target_relevance);

Apply Adjustment

let adjustment = controller.compute_adjustment();
if adjustment.magnitude() > 0.01 {
    controller.apply_adjustment(adjustment);
    println!("Applied adjustment: {:?}", adjustment);
}

Get Deviation Report

let report = controller.deviation_report();
for (param, deviation) in report {
    if deviation.abs() > 0.05 {
        println!("Warning: {} deviation = {:.3}", param, deviation);
    }
}

Tier 2: Detailed Reference

For detailed documentation on:

• PID control implementation
• Stability analysis
• Oscillation damping
• Multi-target coordination

→ See reference.md

Tier 3: Implementation Code

For implementing custom homeostatic controllers:

→ See code/homeostatic_extensions.rs

Common Patterns

Pattern 1: PID Controller

struct PIDController {
    kp: f64,  // Proportional gain
    ki: f64,  // Integral gain
    kd: f64,  // Derivative gain
    integral: f64,
    prev_error: f64,
}

impl PIDController {
    fn compute(&mut self, error: f64, dt: f64) -> f64 {
        self.integral += error * dt;
        let derivative = (error - self.prev_error) / dt;
        self.prev_error = error;

        self.kp * error + self.ki * self.integral + self.kd * derivative
    }
}

Pattern 2: Multi-Target Coordination

fn coordinate_targets(
    controller: &mut HomeostaticController,
    priorities: &[(Target, f64)],  // (target, weight)
) {
    let total_weight: f64 = priorities.iter().map(|(_, w)| w).sum();

    for (target, weight) in priorities {
        let deviation = controller.get_deviation(*target);
        let weighted_adjustment = (weight / total_weight) * deviation;
        controller.adjust(*target, weighted_adjustment);
    }
}

Pattern 3: Stability Check

fn check_stability(controller: &HomeostaticController) -> StabilityStatus {
    let history = controller.get_history(20);  // Last 20 adjustments

    // Check for oscillation
    let sign_changes = history.windows(2)
        .filter(|w| w[0].signum() != w[1].signum())
        .count();

    if sign_changes > 10 {
        return StabilityStatus::Oscillating;
    }

    // Check for divergence
    let recent_magnitude: f64 = history[..5].iter()
        .map(|a| a.abs())
        .sum::<f64>() / 5.0;
    let older_magnitude: f64 = history[15..].iter()
        .map(|a| a.abs())
        .sum::<f64>() / 5.0;

    if recent_magnitude > older_magnitude * 1.5 {
        return StabilityStatus::Diverging;
    }

    StabilityStatus::Stable
}

Homeostatic Feedback Loops

┌─────────────────────────────────────────────────────────────┐
│                   HOMEOSTATIC CONTROL                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────┐    error    ┌────────────┐    adjustment       │
│  │ Target  │─────────────│ Controller │────────────────┐    │
│  │ State   │             │   (PID)    │                │    │
│  └─────────┘             └────────────┘                │    │
│       ▲                                                │    │
│       │                                                ▼    │
│       │                  ┌────────────┐          ┌─────────┐│
│       │                  │  Learning  │◄─────────│ Vortex  ││
│       │                  │   (STDP)   │          │ System  ││
│       │                  └────────────┘          └─────────┘│
│       │                        │                      │     │
│       │                        ▼                      │     │
│       │                  ┌────────────┐               │     │
│       └──────────────────│  Current   │◄──────────────┘     │
│                          │   State    │                     │
│                          └────────────┘                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Integration Points

Database Schema

From migrations/006_module_tensors.sql:

CREATE TABLE homeostatic_state (
    id INTEGER PRIMARY KEY DEFAULT 1,
    target_relevance REAL DEFAULT 0.85,
    target_coherence REAL DEFAULT 0.90,
    target_synergy REAL DEFAULT 0.85,
    adaptation_rate REAL DEFAULT 0.01,
    current_relevance REAL,
    current_coherence REAL,
    current_synergy REAL,
    adjustment_count INTEGER,
    last_adjustment_at TEXT
);

CREATE TABLE homeostatic_adjustments (
    id INTEGER PRIMARY KEY,
    parameter TEXT CHECK (parameter IN ('relevance', 'coherence', 'synergy', 'ltp_rate', 'ltd_rate')),
    old_value REAL,
    new_value REAL,
    delta REAL,
    reason TEXT,
    adjusted_at TEXT
);

Anti-Patterns to Avoid

• AP004: LTP/LTD Imbalance - often caused by poor homeostatic tuning
• AP007: Phase Divergence - may need coupling adjustment via homeostatic control