TEL-14: PV sign declared per entity (pv_invert_entities)

Some PV entities (kWh meters, ESPHome clamps in the PV circuit) read positive
for consumption and negative for production. `pv_invert_entities` lists the
ones to flip; the flip is applied per member inside pv.total(), before the sum,
so the MQTT `pv` row and the status page carry the corrected figure. Default []
is byte-identical to 0.12.0.

Shape measured in supervisor_shape_probe.py section H (Supervisor 2026.08.0):
a parallel list validates the 0.12.0 blob unchanged and renders as its own
translated repeatable field; dicts on pv_entities refuse 0.12.0's stored
strings; a prefix is invisible syntax; a global bool cannot describe a mixed
roster. Status page marks flipped entities and cautions per entity below
-50 W, saying ADD or REMOVE. Telemetry only: control documents unchanged.

Record: DECISIONS/TEL-14-pv-sign.md (reverses TEL-11 section 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU

goodwe_controller/app/main.py

@@ -1726,7 +1726,7 @@ class Controller:
         states = await asyncio.gather(
             *(self.hass.state(entity) for entity in roster))
         self.pv_w, self.pv_why, self.pv_parts = pv_read.total(
-            list(zip(roster, states)))
+            list(zip(roster, states)), pv_read.inverted(self.o))
 
     async def read_inputs(self, now_mono: float | None = None) -> None:
         """Every input this cycle needs, and SAFETY-37's freshness verdict.
@@ -5075,6 +5075,13 @@ class Controller:
         # have to say something the single-entity ones never could.
         roster = self.pv_roster
         if roster:
+            # TEL-14: each flipped entity is marked where its watts are printed;
+            # an unflipped one gets "", so 0.12.0's sentences are unchanged.
+            flip = pv_read.inverted(self.o)
+
+            def inv(ent):
+                return " [sign inverted]" if ent in flip else ""
+
             if len(roster) == 1:
                 if self.pv_w is None:
                     out.append({"ok": False, "warn": True,
@@ -5089,7 +5096,7 @@ class Controller:
                     out.append({"ok": True, "warn": False,
                                 "text": f"PV production: {self.pv_w:.0f} W "
                                         f"from {roster[0]} (reported "
-                                        f"in {self.pv_why})"})
+                                        f"in {self.pv_why})" + inv(roster[0])})
             elif self.pv_w is None:
                 # ⚠️ THE ROW THAT SAYS THERE IS NO TOTAL, AND IT SAYS IT IN
                 # THOSE WORDS. `pv.total()`'s note is the argument; this is
@@ -5104,7 +5111,7 @@ class Controller:
                             "text": "PV production: NO SITE TOTAL - "
                                     + self.pv_why + ". Reporting: "
                                     + (", ".join(
-                                        f"{ent} {watt:.0f} W"
+                                        f"{ent} {watt:.0f} W" + inv(ent)
                                         for ent, watt, _y in self.pv_parts
                                         if watt is not None) or "nothing")})
             else:
@@ -5117,6 +5124,7 @@ class Controller:
                                     f"{len(self.pv_parts)} entities ("
                                     + ", ".join(
                                         f"{ent} {watt:.0f} W in {why}"
+                                        + inv(ent)
                                         for ent, watt, why in self.pv_parts)
                                     + ")"})
             # ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s
@@ -5136,6 +5144,26 @@ class Controller:
                                     f"{len(roster)} entities in the "
                                     "list are what is summed. Clear "
                                     "`pv_entity` to remove this caution"})
+            # TEL-14: a sign that looks reversed, per entity rather than on the
+            # total - see `pv.NEGATIVE_W` and DECISIONS/TEL-14-pv-sign.md §3.
+            for ent, watt, _y in self.pv_parts:
+                if watt is not None and watt < pv_read.NEGATIVE_W:
+                    out.append({"ok": False, "warn": True,
+                                "text": f"PV production: {ent} reads "
+                                        f"{watt:.0f} W - far below zero, so "
+                                        f"its sign is probably reversed. If "
+                                        f"it is producing now, "
+                                        + ("REMOVE it from "
+                                           "`pv_invert_entities`"
+                                           if ent in flip else
+                                           "ADD it to `pv_invert_entities`")
+                                        + " in the Configuration tab"})
+            for ent in pv_read.stray_inverts(self.o):
+                out.append({"ok": False, "warn": True,
+                            "text": f"PV production: `pv_invert_entities` "
+                                    f"names {ent}, which is not a PV entity in "
+                                    f"use, so it flips nothing - check the "
+                                    f"spelling against `pv_entities`"})
         return out
 
     def status_payload(self) -> dict:

goodwe_controller/app/pv.py

@@ -50,21 +50,10 @@ SITE figure, and it publishes as an absence. A partial sum is a second way of
 reporting 0-where-there-was-production, one layer up, and it is refused for the
 same reason.
 
-THE SIGN CONVENTION: POSITIVE IS PRODUCTION. Derived from the two conventions
-this add-on already ships rather than assumed:
-
-    `meter_entity`   positive = IMPORTING from the grid   (DOCS.md, Sources)
-    `batt_entity`    positive = DISCHARGING the pack      (DOCS.md, Sources)
-
-Both are "positive = power arriving at the house's AC bus", and production
-arrives there too. There is deliberately NO `pv_invert` to go with
-`meter_invert` and `batt_invert`: those two quantities are BIPOLAR and are READ
-BY THE CONTROL PATH - a reversed `batt_entity` feeds SAFETY-30's per-unit sign
-check and SAFETY-31's circulating-power sensor with a plausible number the site
-then acts on - whereas production is unipolar and is read by nothing. A reversed
-PV sensor announces itself as -4 kW at noon in the very history this card
-creates, and flipping it here would only hide it. See
-`DECISIONS/TEL-11-pv-production.md` §2.
+THE SIGN CONVENTION: POSITIVE IS PRODUCTION, as for `meter_entity` and
+`batt_entity` ("power arriving at the house's AC bus"). TEL-14: a kWh meter or
+power clamp in the PV circuit reads the other way, so `pv_invert_entities`
+flips the sign per entity. See `DECISIONS/TEL-14-pv-sign.md`.
 """
 
 from .hass import BAD_STATES
@@ -193,7 +182,28 @@ def entity_is_ignored(opts: dict) -> bool:
                      if str(x or "").strip()])
 
 
-def total(readings) -> tuple:
+def inverted(opts: dict) -> frozenset:
+    """The entity ids `pv_invert_entities` flips. TEL-14."""
+    return frozenset(e for e in (str(x or "").strip()
+                                 for x in (opts.get("pv_invert_entities") or []))
+                     if e)
+
+
+def stray_inverts(opts: dict) -> list:
+    """`pv_invert_entities` entries naming no entity in the roster - a typo
+    that would otherwise leave a sign unflipped with nothing said. TEL-14."""
+    roster = set(entities(opts))
+    return sorted(e for e in inverted(opts) if e not in roster)
+
+
+# TEL-14: a reading below this is not standby draw. A correctly signed meter in
+# the PV circuit reads a few watts NEGATIVE at night (the owner's: 13 W); -50 W
+# clears that with room for a couple of such devices on one entity, while a
+# reversed sensor in daylight reads hundreds to thousands of watts below zero.
+NEGATIVE_W = -50.0
+
+
+def total(readings, flip=frozenset()) -> tuple:
     """`(watts, why, parts)` - the SITE's production, or an ABSENCE. TEL-12.
 
     `readings` is `[(entity_id, state), ...]` in `entities()` order, one entry
@@ -237,8 +247,13 @@ def total(readings) -> tuple:
     site: shading, a tripped string and nightfall are all real 0s, and a roster
     that went to `unknown` whenever one member read zero would report an absence
     on every clear evening and defeat the channel from the other end.
+
+    ⚠️ TEL-14: `flip` is `inverted(opts)`; each member's sign is applied HERE,
+    before the sum, so every surface reads the corrected figure. `0.0 - w`
+    rather than `-w`, so a flipped 0 W is `0.0` and never `-0.0` on the wire.
     """
-    parts = [(ent, *watts(st)) for ent, st in readings]
+    parts = [(ent, w if w is None or ent not in flip else 0.0 - w, why)
+             for ent, (w, why) in ((e, watts(st)) for e, st in readings)]
     if not parts:
         # No roster. `Controller` does not call this in that state - the gate is
         # `pv_roster` - but a reader of `parts` should never have to wonder.