goodwe-addon/goodwe_controller/app/store.py

"""Persistent state, in /data (the add-on's only durable volume).

The maintenance cycle is month-scale state: it MUST survive add-on restarts,
HA restarts and power cuts, or the battery quietly stops being maintained and
nothing says so.

Times are stored as ISO-8601 with an explicit UTC offset and parsed back to
aware datetimes. That is not fussiness: the YAML implementation this replaces
was disabled for hours by exactly one naive-vs-aware subtraction, and it failed
silently - the automation never even recorded itself as triggered.
"""

import json
import logging
import os
import tempfile
from datetime import datetime, timezone

_LOG = logging.getLogger("goodwe.store")

# ⚠️ "auto" is deliberately NOT in here. Controller falls back to the add-on's
# `auto_start` option only when the key is absent - if a default supplied False,
# the fallback could never fire and auto_start would silently do nothing on
# every fresh install.
#
# ⚠️ `sign_tripped` IS in here, and the difference from `auto` is the whole
# reason both decisions are written down. `auto` has an option to fall back to
# (`auto_start`), so a stored default would mask a fresh install. A latched
# failsafe has no such fallback: absent means "never tripped", which is exactly
# what a default of False says.
#
# It is persisted for the reason this module's docstring gives for maintenance
# state, applied to something with a much shorter fuse. SAFETY-02's latch is the
# only thing standing between a controller that has been caught driving the wrong
# way and its own restart, and "restart the add-on" is the FIRST thing an operator
# looking at a FAILSAFE banner will try. Held only in memory it came back armed,
# into the fault, unattended - measured: after reconstructing Controller against
# the same store, `tripped` was False, the banner read NOT READY, and it resumed
# commanding -1000, -2000 W before re-tripping 180 s later. Under a supervisor
# that restarts a crashed add-on that is a loop, three minutes of wrong-direction
# power at a time, forever.
#
# ⚠️ AND SINCE DEV-02 THE TWO SAFETY-02 KEYS ARE THE *LEGACY* SPELLING. They are
# FLAT - one `sign_tripped` for a controller that now holds a LIST of inverters -
# so a trip caused by inverter B would latch inverter A across restarts, and one
# operator action would clear both. The LIVE latch is per inverter, under
# `unit/<name>/...`, and that is the one the watchdog is restored from.
#
# ⚠️ THE FLAT PAIR IS NOT DEAD, THOUGH: it is the ROLLBACK VIEW. It is written
# alongside the namespaced keys on a trip and cleared alongside them on the
# operator's clear, so an add-on that is DOWNGRADED past this schema still finds
# the latch it should - and so that a trip taken while the install was rolled
# back is still visible to the version that comes back up. Rule 2 of
# `migrate_unit_keys()` and `Controller._grade_store_migration()` carry the
# argument; the short version is that a latch is only worth persisting if it
# survives the version change an operator makes while staring at the banner.
#
# ⚠️ AND SAFETY-31's PAIR IS FLAT ON PURPOSE, WHICH IS THE OPPOSITE DECISION TO
# THE ONE ABOVE AND NEEDS ITS OWN SENTENCE. `circ_tripped` / `circ_reason` are
# NOT in `LEGACY_UNIT_KEYS` and must never be moved into a unit namespace.
# Circulating power is `sum(|B_i|) - |sum(B_i)|` - a quantity DEFINED over the
# whole roster, which is identically zero for any single unit. There is no fact
# of the matter about which of two opposing inverters is the offender: a unit
# ignoring its share and a sibling faithfully executing a share computed to sum
# with it read identically. Namespacing this latch would mean inventing an
# attribution the measurement cannot support, and would then let an operator
# clear "inverter B's" half of a site-wide loop. One site, one latch.
#
# It is persisted for SAFETY-34's reason, which this add-on has already paid
# for once: `persistent_notification` is IN MEMORY. Home Assistant restarts and
# the card is gone while the fault runs on - exactly how the 2026-09-02 outage
# went unseen for 6 h 25 m with the detector correct throughout. main.py
# re-raises the notification from this key on every start.
#
# ⚠️ AND SAFETY-30's PAIR IS FLAT FOR THE SAME REASON SAFETY-31's IS, WHICH IS
# NOT THE SAME REASON THE ONES ABOVE ARE NAMESPACED. `site_sign_tripped` /
# `site_sign_reason` hold the SITE sign-disagreement latch: the SUM of every
# standing command opposed the meter, continuously. That is a statement about
# the grid connection - the offending number is the site target, which no single
# inverter owns - so there is no unit to hang it on, and hanging it on one would
# let an operator clear "inverter B's half" of a fault that has no halves.
# `unit/<name>/sign_tripped` above stays what it always was and now means what
# it says: THAT unit's own command against THAT unit's own measured power.
#
# ⚠️ AND THEY ARE NOT IN `LEGACY_UNIT_KEYS`, MUST NEVER BE, AND ARE NOT WRITTEN
# AT A ROSTER OF ONE AT ALL. At N=1 the site comparison and the unit comparison
# are the same sentence and `Controller.cycle()` arms only the per-unit
# detector, so a one-inverter install's state file is byte-identical to what it
# was before this card - these two keys sit at their defaults and nothing reads
# them. A rollback therefore finds exactly the flat `sign_tripped` mirror it
# always found.
DEFAULTS = {
    "phase": "idle",
    "phase_started": None,
    "last_completed": None,
    "last_start_attempt": None,
    "sign_tripped": False,
    "sign_reason": "",
    "circ_tripped": False,
    "circ_reason": "",
    "site_sign_tripped": False,
    "site_sign_reason": "",
}

# --------------------------------------------------------------------------- #
# DEV-02: PER-INVERTER KEYS, AND THE MIGRATION IS THE RISKY HALF
#
# ⚠️ A LATCH THAT SILENTLY FAILS TO MIGRATE IS A DISARMED SAFETY GUARD ON AN
# INSTALL THAT BELIEVES IT IS PROTECTED. SAFETY-02's whole reason for being
# persisted is that "restart the add-on" is the FIRST thing an operator staring
# at a FAILSAFE banner tries, and a latch held only in memory comes back armed,
# into the fault, unattended. A latch that is written down under a key nothing
# reads any more is exactly the same failure with a longer paper trail: the file
# still says `sign_tripped: true`, the banner is green, and the controller
# resumes driving the wrong way.
#
# So this is a MIGRATION WITH A POSTCONDITION, not a copy. `migrate_unit_keys()`
# reports what it did AND reads the result back; `Controller.__init__` grades
# that report and refuses to come up quietly if the latch did not survive. The
# test that grades it BREAKS the migration and watches the guard fire.
# --------------------------------------------------------------------------- #

# 0 = the flat, one-inverter layout that shipped before DEV-02.
# 1 = per-inverter keys under `unit/<name>/...`.
SCHEMA_VERSION = 1
SCHEMA_KEY = "schema_version"

# Which flat keys belong to ONE inverter, and therefore move into its namespace.
# ⚠️ THE MAINTENANCE KEYS ARE NOT IN HERE AND THAT IS DELIBERATE. `phase`,
# `phase_started`, `last_completed` and `last_start_attempt` belong to the
# maintenance state machine, of which this add-on still holds exactly ONE - a
# monthly recalibration is a pack procedure and per-pack SCHEDULING is a card of
# its own, not something to infer from a key rename. Moving them here would
# quietly re-home an install's whole maintenance history under a unit name; they
# stay where they are, untouched, which is the other half of "migrates without
# losing its latch OR ITS HISTORY".
LEGACY_UNIT_KEYS = ("sign_tripped", "sign_reason")


def unit_key(unit: str, key: str) -> str:
    """The namespaced Store key for `key` on inverter `unit`.

    ⚠️ ONE SPELLING, IN ONE PLACE. `Inverter.key()` calls this and so does the
    migration, so a check can assert that what was migrated is what is read.
    Two transcriptions of a key name is one copy plus a future disagreement
    about which one holds the latch - and the copy that drifts is always the one
    that reads.
    """
    return f"unit/{unit}/{key}"


class MigrationReport:
    """What `migrate_unit_keys()` did, and whether it can be believed.

    ⚠️ IT CARRIES `verified`, WHICH IS READ BACK FROM THE STORE RATHER THAN
    ASSUMED FROM THE ASSIGNMENT. That is the difference between this and a
    two-line copy: the caller is able to ask "is the latch that was in the file
    before now under the key the watchdog reads", and a `False` there is a
    disarmed guard, which is an ERROR and not a log line nobody sees.
    """

    def __init__(self):
        self.ran = False            # did anything need moving
        self.from_version = 0
        self.moved = {}             # new key -> value written
        self.kept = []              # keys already namespaced, left alone
        self.verified = True        # every move read back equal
        self.problems = []          # human-readable, one per failed move
        # ⚠️ THE SUBSET THAT MATTERS, AND THE DISTINCTION IS NOT PEDANTRY. A
        # store that drops a write of `sign_tripped=False` has lost the
        # DEFAULT - the same statement "absent" already makes, so nothing is
        # gone. One that drops a write of `True` has lost A LATCH. Only the
        # second is a disarmed safety guard, and only the second may be allowed
        # to shout: an alarm that fires on the harmless case is an alarm an
        # operator learns to dismiss before the real one arrives.
        self.lost = []

    @property
    def ok(self) -> bool:
        """Nothing that CARRIED STATE failed to land."""
        return not self.lost

    def explain(self) -> str:
        if not self.ran:
            return (f"store already at schema {self.from_version}; no "
                    f"per-inverter migration needed")
        out = (f"migrated {len(self.moved)} flat key(s) to inverter "
               f"namespaces: " + ", ".join(sorted(self.moved)))
        if self.kept:
            out += " (left alone, already namespaced: " + ", ".join(sorted(self.kept)) + ")"
        if self.problems:
            out += " - PROBLEMS: " + "; ".join(self.problems)
        if self.lost:
            out += " - STATE LOST: " + "; ".join(self.lost)
        return out


def migrate_unit_keys(store, unit: str) -> MigrationReport:
    """Move the pre-DEV-02 flat per-inverter keys into `unit`'s namespace.

    `unit` is the FIRST inverter in the roster, which on every install that can
    possibly have a flat key is the only one it ever had. A store written by a
    version that knew about more than one inverter is already at
    SCHEMA_VERSION and is not touched.

    THE THREE RULES, each one a case that would otherwise be a wrong answer:

    1. IT NEVER OVERWRITES AN EXISTING NAMESPACED VALUE. A store that has both
       spellings has been written by this version, and the namespaced one is
       where the WATCHDOG is restored from. Preferring the flat one HERE would
       resurrect a trip the operator has already cleared, because a migration
       runs before anything can tell the two apart. Deciding between them is
       main.py's job and it has the one rule that can: the flat key carries new
       information only when NOTHING namespaced is latched.
    2. THE FLAT KEYS ARE LEFT IN THE FILE, AND THEY ARE KEPT LIVE. Deleting
       them buys tidiness and costs a rollback: an operator who downgrades the
       add-on after a migration would find no latch at all, which is the
       disarmed guard again in the other direction. Left in place, a downgrade
       finds the trip it had.

       ⚠️ AND "LEFT IN PLACE" IS NOT ENOUGH ON ITS OWN, WHICH IS WHAT THIS RULE
       USED TO SAY. The sentence here read "they go stale from this moment -
       nothing writes them again - and the direction that staleness fails in is
       a SPURIOUS latch, never a missing one". That was true of the latch this
       migration MOVES and false of every trip that happens AFTERWARDS: nothing
       flat was written for those, so a rollback found `sign_tripped: false` and
       came up DRIVING. So main.py mirrors both keys on a trip and clears both
       on the operator's clear. The flat pair is the ROLLBACK VIEW of the latch,
       maintained, not a fossil - which is also what lets main.py's
       `_grade_store_migration()` run on every start and catch a trip that
       happened while the install was rolled back (see its docstring: the flat
       key saying tripped while no inverter came up tripped is the one
       disagreement that can occur, and it is a DOWNGRADE-WINDOW LATCH).
    3. THE VERSION MARKER IS WRITTEN LAST. A crash between the copies and the
       marker leaves the migration to run again, and rule 1 makes running it
       again a no-op. A marker written first would leave a half-migrated store
       looking finished.
    """
    rep = MigrationReport()
    data = getattr(store, "data", {})
    rep.from_version = int(data.get(SCHEMA_KEY, 0) or 0)
    if rep.from_version >= SCHEMA_VERSION:
        return rep

    rep.ran = True
    for legacy in LEGACY_UNIT_KEYS:
        target = unit_key(unit, legacy)
        if target in data:
            rep.kept.append(target)
            continue
        # ⚠️ `DEFAULTS[legacy]` RATHER THAN A LITERAL. An install that never
        # tripped has no `sign_tripped` in its file at all, and the value it
        # then lands on has to be the one `Store.load()` would have supplied -
        # otherwise "absent" and "never tripped" stop being the same statement,
        # which is the distinction store.py's own header is about.
        value = data.get(legacy, DEFAULTS.get(legacy))
        store.set(target, value)
        rep.moved[target] = value

    # THE POSTCONDITION, AND IT IS A READ-BACK RATHER THAN AN ASSUMPTION. This
    # is the difference between this function and a two-line copy: the caller
    # can ask "is the latch that was in the file before now under the key the
    # watchdog reads", through the same `unit_key()` the watchdog's constructor
    # reads through, and a `False` there is a guard that is off on an install
    # whose state file says it is on.
    for target, value in rep.moved.items():
        got = getattr(store, "data", {}).get(target, "<<missing>>")
        if got == value:
            continue
        rep.verified = False
        note = f"{target} was written as {value!r} and reads back as {got!r}"
        rep.problems.append(note)
        legacy = target.rsplit("/", 1)[-1]
        if value != DEFAULTS.get(legacy):
            rep.lost.append(note)

    if rep.ok:
        store.set(SCHEMA_KEY, SCHEMA_VERSION)
    else:
        # ⚠️ NOT MARKED DONE. A migration that lost state must run again on the
        # next start rather than be recorded as finished - the one thing worse
        # than a failed migration is a failed migration a later version skips.
        _LOG.error("per-inverter store migration LOST STATE and has not been "
                   "marked done: %s", rep.explain())
    return rep


class Store:
    def __init__(self, path: str = "/data/state.json"):
        self.path = path
        self.data = dict(DEFAULTS)
        self.load()

    def load(self) -> None:
        try:
            with open(self.path, "r", encoding="utf-8") as fh:
                loaded = json.load(fh)
            if isinstance(loaded, dict):
                self.data = {**DEFAULTS, **loaded}
                _LOG.info("state restored: phase=%s last_completed=%s "
                          "sign_tripped=%s",
                          self.data.get("phase"), self.data.get("last_completed"),
                          self.data.get("sign_tripped"))
        except FileNotFoundError:
            _LOG.info("no saved state, starting fresh")
        except (json.JSONDecodeError, OSError) as err:
            # A corrupt state file must not stop the controller: losing the
            # maintenance history is recoverable, refusing to run is not.
            _LOG.warning("state unreadable (%s) - starting fresh", err)

    def save(self) -> None:
        # Atomic replace: a power cut mid-write must not leave a truncated file
        # that reads as "no maintenance ever ran".
        try:
            os.makedirs(os.path.dirname(self.path), exist_ok=True)
            fd, tmp = tempfile.mkstemp(dir=os.path.dirname(self.path))
            with os.fdopen(fd, "w", encoding="utf-8") as fh:
                json.dump(self.data, fh, indent=1)
            os.replace(tmp, self.path)
        except OSError as err:
            _LOG.error("could not persist state: %s", err)

    # -- typed helpers ------------------------------------------------------
    def get_time(self, key: str):
        raw = self.data.get(key)
        if not raw:
            return None
        try:
            parsed = datetime.fromisoformat(raw)
        except (TypeError, ValueError):
            _LOG.warning("unparseable timestamp for %s: %r", key, raw)
            return None
        # Anything that ever escaped without an offset is treated as UTC rather
        # than raising later in an arithmetic expression.
        return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)

    def set_time(self, key: str, when: datetime | None) -> None:
        self.data[key] = when.astimezone(timezone.utc).isoformat() if when else None
        self.save()

    def set(self, key: str, value) -> None:
        self.data[key] = value
        self.save()