Handle B2500 pass-through at 100% SoC (#338)

Reported by the repo owner as a follow-up: when the B2500 is at 100%
SoC any incoming DC solar flows straight through as AC output, so it
reports positive power regardless of commands.  Against the pre-fix
balancer this pins the Venus around -340 W via the balance-correction
+ sign-clamp interaction, leaving ~160 W of sustained feed-in — and
reproduces the user's symptom without any Venus startup-threshold
assumption.

The earlier commit fixed the split-evenly deadlock but the strict
``grid_total < 0`` guard let go at the exact zero-crossing during
pass-through equilibrium (Venus at -500 W, B2500 at +500 W, grid at
0 W): the balance-correction fired, pushed Venus positive by one
max_correction_per_step, and the system oscillated.

Extend the charge-blind mask to also fire at ``grid_total == 0`` when
any AC-chargeable battery is currently charging (``power < 0``).
That signals pass-through equilibrium specifically, and keeps the
discharge path untouched — a pure-discharge equilibrium at grid=0
has both batteries at positive power, so the extension doesn't
activate.

Adds ``B2500PassThrough`` to the test harness and a regression test
verifying Venus converges to -500 W and grid to 0 W under the
500 W pass-through scenario.

Author: claude

src/astrameter/ct002/balancer.py

@@ -832,18 +832,34 @@ def _compute_auto_target(
         num_consumers = max(1, len(reports))
         eff_part = {cid: max(0.01, 1.0 - saturation.get(cid, 0.0)) for cid in reports}
 
-        # Exclude DC-only batteries (B2500 family, Jupiter, anything not in
-        # AC_CHARGEABLE_DEVICE_PREFIXES) from charge distribution under
-        # surplus.  They'll happily discharge on positive grid_total, but
-        # asking them to charge wastes the share that should have gone to
-        # the AC sibling (Venus).  See issue #338.
+        # Exclude DC-only batteries (B2500 family, Jupiter, anything not
+        # in AC_CHARGEABLE_DEVICE_PREFIXES) from charge distribution
+        # whenever the grid is in charge territory.  The base gate is
+        # ``grid_total < 0`` (surplus), but we also extend it to the
+        # exact zero-crossing when an AC-chargeable battery is already
+        # charging (``power < 0``) — that signals pass-through
+        # equilibrium, which happens when a full B2500 is passing its DC
+        # solar input through as AC output (+P W) while the Venus
+        # charges a matching -P W, leaving grid at 0.  Without this
+        # extension the balance-correction fires at the zero-crossing
+        # and oscillates the Venus back out of its steady state.  We
+        # deliberately don't fire on ``grid_total == 0`` during pure
+        # discharge (both batteries discharging to serve the house load)
+        # because no AC-chargeable battery is charging there.
+        # See issue #338.
+        ac_charging = any(
+            _is_ac_chargeable(r.get("device_type", ""))
+            and parse_int(r.get("power", 0)) < 0
+            for r in reports.values()
+        )
+        in_charge_territory = grid_total < 0 or (grid_total == 0 and ac_charging)
         charge_blind = (
             {
                 cid
                 for cid, r in reports.items()
                 if not _is_ac_chargeable(r.get("device_type", ""))
             }
-            if grid_total < 0
+            if in_charge_territory
             else set()
         )
         for cid in charge_blind:

tests/test_balancer_mixed_battery_charging.py

@@ -140,6 +140,37 @@ def step(self, target_delta: float, reported_power: float) -> None:
             self.power = 0.0
 
 
+class B2500PassThrough:
+    """B2500 at 100 % SoC passing its DC solar input straight through as AC.
+
+    When the B2500 is full it can no longer absorb its own DC input, so
+    the excess flows out as AC — the unit reports positive power
+    (apparent discharge) regardless of any CT command.  The balancer
+    sees this as "B2500 is producing" while the real grid is still
+    importing the surplus it can't absorb.  See issue #338 (follow-up
+    from the repo owner): this scenario reproduces the deadlock
+    *without* requiring any Venus startup-threshold assumption, because
+    the balance-correction + sign-clamp interaction alone pins the
+    Venus below the level needed to cancel the B2500's feed.
+    """
+
+    def __init__(
+        self,
+        mac: str,
+        passthrough_w: int,
+        *,
+        device_type: str = "HMJ-1",
+    ) -> None:
+        self.mac = mac
+        self.passthrough_w = passthrough_w
+        self.device_type = device_type
+        self.power = float(passthrough_w)
+
+    def step(self, target_delta: float, reported_power: float) -> None:
+        # Output is dictated by DC solar input, not the CT command.
+        self.power = float(self.passthrough_w)
+
+
 def _make_balancer(clock: _FakeClock) -> LoadBalancer:
     """Balancer with CT002 defaults (matching the out-of-the-box config)."""
     return LoadBalancer(
@@ -317,6 +348,50 @@ def test_non_venus_prefixes_are_treated_as_dc(dc_device_type: str) -> None:
     )
 
 
+# ---------------------------------------------------------------------------
+# B2500 pass-through at 100 % SoC
+# ---------------------------------------------------------------------------
+
+
+def test_b2500_passthrough_at_full_soc_does_not_pin_venus() -> None:
+    """B2500 full + passing 500 W DC through as AC: Venus must absorb it.
+
+    Without the fix the pre-fix balancer pins the Venus at ~-340 W: the
+    balance correction treats the B2500's +500 W "output" as a peer
+    behaviour the Venus should match toward, and the sign clamp then
+    blocks Venus from being pushed negative enough to cancel the feed.
+    The result is a sustained ~160 W export, independent of any
+    inverter startup threshold.
+
+    With the fix, the B2500 is recognised by prefix (``HMJ-1``) as
+    DC-only and excluded from charge distribution; the Venus receives
+    the full -500 W target, charges to -500 W, and pins the grid at 0.
+    """
+    b2500 = B2500PassThrough("b2500_full", passthrough_w=500)
+    venus = ACBatteryWithStartupThreshold("venus", device_type="HMG-50")
+
+    grid, power = _run_scenario([b2500, venus], surplus_watts=0.0, ticks=60)
+
+    venus_tail = power["venus"][-20:]
+    b2500_tail = power["b2500_full"][-20:]
+    grid_tail = grid[-20:]
+
+    # B2500 keeps pushing its 500 W pass-through regardless of commands.
+    assert all(abs(p - 500.0) < 1.0 for p in b2500_tail), (
+        f"B2500 pass-through output should stay at 500 W, tail was {b2500_tail}"
+    )
+    # Venus absorbs the full pass-through; grid at ~0.
+    assert min(venus_tail) < -490, (
+        f"Venus should converge near -500 W to cancel the pass-through, "
+        f"tail was {venus_tail}"
+    )
+    avg_grid = sum(grid_tail) / len(grid_tail)
+    assert abs(avg_grid) < 30, (
+        f"Grid should converge near 0 W (Venus exactly cancels B2500), "
+        f"got {avg_grid:.0f} W"
+    )
+
+
 # ---------------------------------------------------------------------------
 # Discharge unaffected
 # ---------------------------------------------------------------------------