Fix false saturation detection during load sign reversal (#301)

* Fix false saturation detection during load sign reversal

When the grid target flips sign (e.g. solar excess causes discharge→charge),
batteries ramping through zero were falsely detected as saturated because
abs(actual) < min_target during the reversal. This caused ping-pong rotation
between batteries.

The fix treats sign disagreement between target and actual as a direction
reversal (not saturation) and decays the score instead of accumulating it.

https://claude.ai/code/session_01TowsqcPQ2jQMqo7PXDCYSm

* Remove changelog entry for saturation fix

https://claude.ai/code/session_01TowsqcPQ2jQMqo7PXDCYSm

* Add unit tests for sign-reversal guard boundary cases

- actual=0 does not trigger the guard (no sign to disagree)
- target=0 does not trigger the guard (handled by low-target decay)
- After reversal ends (actual crosses zero), accumulation resumes

https://claude.ai/code/session_01TowsqcPQ2jQMqo7PXDCYSm

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tomquist

src/b2500_meter/ct002/balancer.py

@@ -173,7 +173,15 @@ def update(
             else:
                 state.saturation_grace_until = 0.0
                 state.saturation_grace_started_at = 0.0
-        if target_abs < self._min_target:
+        # Detect sign reversal: target says one direction, actual is still
+        # in the opposite direction.  The battery is healthy but ramping to
+        # the new direction — not saturated.  Treat like low-target (decay).
+        target_sign = 1 if last_target > 0 else (-1 if last_target < 0 else 0)
+        actual_sign = 1 if actual > 0 else (-1 if actual < 0 else 0)
+        sign_reversing = (
+            target_sign != 0 and actual_sign != 0 and target_sign != actual_sign
+        )
+        if target_abs < self._min_target or sign_reversing:
             prev = state.saturation_score
             if prev > 0:
                 decayed = prev * self._decay_factor

tests/test_balancer.py

@@ -159,6 +159,98 @@ def test_get(self):
         state = BalancerConsumerState(saturation_score=0.7)
         assert tracker.get(state) == 0.7
 
+    def test_sign_reversal_decays_instead_of_accumulating(self):
+        """When target and actual have opposite signs (direction reversal),
+        saturation should decay rather than accumulate."""
+        tracker = self._make_tracker(alpha=0.15, min_target=20, decay_factor=0.995)
+        state = BalancerConsumerState()
+
+        # Battery discharging at 100W, tracking well
+        for _ in range(5):
+            tracker.update(state, last_target=100.0, actual=95.0)
+        assert state.saturation_score < 0.01
+
+        # Target flips to charge (-100W), but actual is still +80W (ramping)
+        for _ in range(20):
+            tracker.update(state, last_target=-100.0, actual=80.0)
+        # Score must NOT have accumulated — should have stayed near zero
+        assert state.saturation_score < 0.01, (
+            f"Saturation score {state.saturation_score:.3f} should not "
+            f"accumulate during sign reversal"
+        )
+
+    def test_sign_reversal_existing_score_decays(self):
+        """Pre-existing saturation score decays during sign reversal."""
+        tracker = self._make_tracker(decay_factor=0.9)
+        state = BalancerConsumerState(saturation_score=0.5)
+
+        # Target positive, actual negative (battery reversing)
+        for _ in range(10):
+            tracker.update(state, last_target=100.0, actual=-50.0)
+        assert state.saturation_score < 0.5, (
+            f"Score should decay during sign reversal, got {state.saturation_score:.3f}"
+        )
+
+    def test_same_sign_low_output_still_accumulates(self):
+        """When signs agree but output is below min_target, saturation
+        should still accumulate (genuine saturation)."""
+        tracker = self._make_tracker(alpha=0.15, min_target=20)
+        state = BalancerConsumerState()
+
+        # Target +100W but actual only +5W (same sign, truly saturated)
+        for _ in range(20):
+            tracker.update(state, last_target=100.0, actual=5.0)
+        assert state.saturation_score > 0.4, (
+            f"Saturation score {state.saturation_score:.3f} should accumulate "
+            f"when signs agree but output is low"
+        )
+
+    def test_actual_zero_during_reversal_does_not_trigger_guard(self):
+        """actual=0 should NOT activate the sign-reversal guard (actual
+        has no sign), so saturation accumulates normally."""
+        tracker = self._make_tracker(alpha=0.15, min_target=20)
+        state = BalancerConsumerState()
+
+        # Target is -100W (charge) but actual is exactly 0
+        for _ in range(20):
+            tracker.update(state, last_target=-100.0, actual=0.0)
+        assert state.saturation_score > 0.4, (
+            f"Saturation score {state.saturation_score:.3f} should accumulate "
+            f"when actual is zero (no sign to disagree)"
+        )
+
+    def test_target_zero_does_not_trigger_guard(self):
+        """target=0 should NOT activate the sign-reversal guard."""
+        tracker = self._make_tracker(alpha=0.15, min_target=20, decay_factor=0.995)
+        state = BalancerConsumerState(saturation_score=0.5)
+
+        # Target is 0, actual is positive — target_abs < min_target so
+        # the low-target decay path handles this, not the sign guard.
+        for _ in range(10):
+            tracker.update(state, last_target=0.0, actual=50.0)
+        # Score should have decayed via the low-target path
+        assert state.saturation_score < 0.5
+
+    def test_sign_reversal_then_same_sign_resumes_accumulation(self):
+        """After a sign reversal period, once actual crosses zero to match
+        target sign, saturation tracking resumes normally."""
+        tracker = self._make_tracker(alpha=0.15, min_target=20)
+        state = BalancerConsumerState()
+
+        # Phase 1: sign reversal — target negative, actual positive
+        for _ in range(10):
+            tracker.update(state, last_target=-100.0, actual=50.0)
+        score_after_reversal = state.saturation_score
+        assert score_after_reversal < 0.01
+
+        # Phase 2: actual crosses zero but is small (same sign, low output)
+        for _ in range(20):
+            tracker.update(state, last_target=-100.0, actual=-5.0)
+        assert state.saturation_score > 0.4, (
+            f"Saturation score {state.saturation_score:.3f} should accumulate "
+            f"once signs agree again"
+        )
+
 
 class TestLoadBalancerLifecycle:
     def _make_balancer(self, **kwargs):

tests/test_efficiency_e2e.py

@@ -698,3 +698,59 @@ async def test_saturation_recovery_after_swap(self):
             )
         finally:
             await h.stop()
+
+    async def test_load_sign_reversal_does_not_cause_false_saturation(self):
+        """When load flips sign (discharge->charge), active battery must not
+        be falsely detected as saturated while it ramps to the new direction.
+
+        Reproduces the real-world ping-pong observed when solar production
+        changes cause the grid target to flip sign.
+        """
+        h = _SimHarness(
+            num_batteries=2,
+            base_load=[200.0, 0.0, 0.0],
+            min_efficient_power=150,
+            efficiency_rotation_interval=9999,  # no timed rotation
+            efficiency_fade_alpha=1.0,
+            efficiency_saturation_threshold=0.4,
+            saturation_stall_timeout_seconds=60.0,
+        )
+        await h.start()
+        try:
+            # Let system settle with one battery discharging
+            await h.step_until(lambda: h.active_battery_count() == 1)
+            await h.step(10)
+
+            active_idx = h.active_battery_indexes()[0]
+            other_idx = 1 - active_idx
+            assert h.battery_powers()[active_idx] > 100
+
+            # Flip load sign: go from 200W discharge to -200W (solar excess)
+            h.load_model.base_load[0] = -200.0
+
+            # Step through the sign reversal -- the active battery must NOT
+            # be swapped out due to false saturation.
+            # 60 steps at 0.3s/step = 18s, plenty for old bug to trigger.
+            rotations = 0
+            for _ in range(60):
+                await h.step()
+                powers_after = h.battery_powers()
+                # Detect rotation: other battery becomes sole active
+                if (
+                    abs(powers_after[other_idx]) > 15
+                    and abs(powers_after[active_idx]) < 15
+                ):
+                    rotations += 1
+
+            # The battery should have reversed direction (now charging)
+            assert h.battery_powers()[active_idx] < -50, (
+                f"Active battery should be charging after sign reversal. "
+                f"Powers: {h.battery_powers()}"
+            )
+            # No false-saturation rotation should have occurred
+            assert rotations == 0, (
+                f"Battery was falsely rotated {rotations} time(s) during "
+                f"sign reversal. Powers: {h.battery_powers()}"
+            )
+        finally:
+            await h.stop()