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 STILL NOT IN HERE, AND SINCE MAINT-05 THAT IS A
# DIFFERENT DECISION RATHER THAN THE SAME ONE. They DO move now - one
# `Maintenance` per roster entry needs one history per roster entry - but they
# move on their OWN marker, `MAINT_SCHEMA_KEY`, and only on a site that actually
# has more than one pack. Two conditions the SAFETY-02 keys do not share, so
# folding them into this tuple would either drag them across on a
# single-inverter install (which is the byte-identical store layout MAINT-05
# must not change) or hold the sign latch hostage to a roster count it has
# nothing to do with. `MAINT_UNIT_KEYS` below carries them.
LEGACY_UNIT_KEYS = ("sign_tripped", "sign_reason")

# --------------------------------------------------------------------------- #
# MAINT-05: THE SECOND MIGRATION, AND WHY IT IS A SECOND ONE
#
# 0 = the flat, one-history layout every install has had since the add-on
#     shipped: `phase` / `phase_started` / `last_completed` /
#     `last_start_attempt` describe THE pack, because there was one FSM.
# 1 = one history per roster entry, under `unit/<name>/...`.
#
# ⚠️ ITS OWN MARKER, NOT A BUMP OF `SCHEMA_VERSION`, AND THE REASON IS THAT THE
# TWO MIGRATIONS DO NOT HAVE THE SAME PRECONDITION. DEV-02's runs on every
# install exactly once and is monotone in the version number. This one runs ONLY
# WHERE THE ROSTER HAS MORE THAN ONE PACK, because at N=1 §6.2's identity holds
# and the flat keys ARE that pack's namespace - moving them would add four keys
# and a version marker to a store MAINT-05's own acceptance criterion requires
# to be byte-identical. A single monotone counter cannot express "migrated on
# this site, deliberately not migrated on that one" without lying to the next
# version that reads it: a one-inverter store would have to be left at the old
# number forever, and then a genuine v2 migration could never be told apart from
# a site that simply never grew.
#
# ⚠️ AND IT IS TWO MARKERS, NOT TWO COPIES OF THE THREE RULES.
# `_move_flat_keys()` and `_verify_moves()` below are shared verbatim by both
# migrations, so rules 1 and 3 and the READ-BACK POSTCONDITION are one
# implementation. A second transcription of a migration is a second opinion
# about what "it landed" means.
MAINT_SCHEMA_VERSION = 1
MAINT_SCHEMA_KEY = "maint_schema_version"

# The flat maintenance-history keys, in the order they are moved.
# ⚠️ THE VALUES ARE THE FLAT SPELLINGS AND THE MODULE THAT READS THEM INDEXES
# THIS SAME TUPLE (`maintenance.UnitHistory`), so a key renamed here cannot
# silently stop being migrated - the same property `UNIT_STORE_KEYS` gives the
# SAFETY-02 pair.
MAINT_UNIT_KEYS = ("phase", "phase_started", "last_completed",
                   "last_start_attempt")


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 = []
        # ⚠️ A DIFFERENT FAILURE FROM `lost`, AND IT HAS TO BE, BECAUSE THE
        # READ-BACK CANNOT SEE IT. `lost` is "the store took the write and
        # dropped it". This is "the store took the write, kept it perfectly, and
        # NOTHING WILL EVER READ IT" - the migration was handed a unit name that
        # is not on the roster, so every machine looks under a different key and
        # finds nothing. There is no harmless-default version of this the way
        # there is for `lost`: a write nobody reads is not information, whatever
        # its value, so anything in here fails `ok` on its own.
        self.misdirected = []
        # Why nothing ran, when nothing ran. Empty means "already at schema".
        self.skipped = ""

    @property
    def ok(self) -> bool:
        """Nothing that CARRIED STATE failed to land, and it landed WHERE THE
        MACHINES LOOK."""
        return not self.lost and not self.misdirected

    def explain(self) -> str:
        if not self.ran:
            # ⚠️ `skipped` RATHER THAN A SECOND SENTENCE ABOUT VERSIONS. Since
            # MAINT-05 there are two reasons a migration does not run - the
            # store is already at this schema, or the roster has one pack and
            # the flat keys ARE its namespace - and an operator reading the
            # startup log needs to be told which, because only one of them
            # changes when a second inverter is declared.
            return self.skipped or (f"store already at schema "
                                    f"{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)
        if self.misdirected:
            out += " - WRONG NAMESPACE: " + "; ".join(self.misdirected)
        return out


def migrate_unit_keys(store, unit: str, roster=None) -> 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.

    ⚠️ `roster` IS THE NAMES THE MACHINES READ, AND IT IS SAFETY-44. This
    function shipped WITHOUT it, taking a hardcoded `inverter.UNIT_A` at its one
    call site - which is, exactly, the MAINT-05 defect `_verify_moves()` spends
    a paragraph describing, still live in the sibling that paragraph was written
    beside. On a store that ran pre-DEV-02 flat and declares
    `inverters: [garage, shed]`, the latch moved to `unit/inverter-a/
    sign_tripped`, was read back under that same name, was SATISFIED, and
    stamped the marker - so the next start skipped the migration too and NO
    inverter came up latched on an install whose state file says `sign_tripped:
    true`. A disarmed SAFETY-02 guard, every symptom of a clean migration.

    `roster_names(opts)` answers this BEFORE any `Inverter` exists - it is
    defined to, for `MqttPublisher`, which is constructed before the roster for
    the same reason - so the "there is no roster yet" that kept this argument
    out was never true. On the flat shape it returns `[UNIT_A]`, so the upgrade
    every install runs today passes `unit == roster[0] == UNIT_A` and is
    byte-identical.

    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
    _move_flat_keys(store, unit, LEGACY_UNIT_KEYS, rep)
    _verify_moves(store, rep, roster)

    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("Moving the saved state to one part per inverter lost "
                   "data, so it is not marked done: %s", rep.explain())
    return rep


def _move_flat_keys(store, unit: str, keys, rep: MigrationReport) -> None:
    """Rule 1, once, for both migrations.

    Copies each flat `key` to `unit/<unit>/<key>` UNLESS the namespaced spelling
    is already present - a store that has both has been written by a version
    that knew about the namespace, and that value is the live one. Rule 2 is the
    absence of a delete: the flat keys are left exactly where they were.
    """
    data = getattr(store, "data", {})
    for legacy in 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. The same
        # sentence holds for `last_completed`: absent means "never recalibrated"
        # and a literal here would be a second opinion about that.
        value = data.get(legacy, DEFAULTS.get(legacy))
        store.set(target, value)
        rep.moved[target] = value


def _verify_moves(store, rep: MigrationReport, roster=None) -> None:
    """THE POSTCONDITION, AND IT IS A READ-BACK RATHER THAN AN ASSUMPTION.

    This is the difference between these functions 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" - and, since MAINT-05, "is the history that was in the
    file before now under the key THIS PACK's state machine reads" - through the
    same `unit_key()` those readers read through. A `False` here is a guard that
    is off, or a month of coulomb-count history gone, on an install whose state
    file says otherwise.

    ⚠️ AND `roster` IS THE OTHER HALF, WHICH THE READ-BACK ON ITS OWN CANNOT BE.
    A POSTCONDITION THAT READS BACK THE NAMESPACE IT WAS HANDED CANNOT DETECT
    BEING HANDED THE WRONG ONE. That is not a hypothetical: MAINT-05 shipped
    with `migrate_maint_keys()` taking a bare `unit` string, and a call site that
    passed `inverter.UNIT_A` instead of the first roster entry's name migrated an
    install's whole maintenance history into `unit/inverter-a/...` on a roster of
    `["garage", "shed"]`, read all four keys back under that same name, was
    SATISFIED, and stamped the schema marker - so the next start skipped the
    migration too and both packs came up believing they had never been
    recalibrated. Every symptom of a clean migration, and the history gone.
    `build_roster()` names a declared roster's entries from the config and falls
    back to a POSITIONAL `inverter-N`, so `inverter-a` is not even the default
    there; there is no roster on which that write could have been read.

    So the namespace is graded against the one the MACHINES read - the roster -
    rather than against the argument this function was handed, which is the
    thing under test. A unit that is not on the roster is `misdirected`, which
    fails `ok`, which means the caller does NOT stamp the version marker and the
    next start runs the migration again. A re-run is recoverable, by rule 1; a
    silent skip is the state store.py's header says must never happen.

    ⚠️ AND THE GRADED SET IS `moved` UNION `kept`, WHICH IS WHAT MAKES THAT
    PARAGRAPH TRUE ON THE SECOND START AS WELL AS THE FIRST. Graded over `moved`
    alone the refusal lasted exactly one start: the wrong call site is still
    wrong next time, finds the keys it wrote already present, and rule 1 routes
    every one of them to `kept` - so `moved` is empty, this loop sees nothing,
    `ok` comes back True and the marker is stamped on a migration that has
    reached no readable key. The measurement is in the comment on the loop
    itself. `test_maintenance.py` section 9c calls this twice with the SAME
    wrong `unit` over one store, which is the shape nothing in the suite had.

    `roster=None` still means "not graded", and SAFETY-44 is what it cost. This
    paragraph used to end here, saying that the one caller passing it was
    `migrate_unit_keys()`, "which runs BEFORE `build_roster()` ... so the keys
    have to be in place before there is a roster to check against", and calling
    that gap real. THE FIRST HALF IS TRUE AND THE CONCLUSION IS NOT. The keys do
    have to be written before the `Inverter`s restore from them - but the NAMES
    do not come from the `Inverter`s. `roster_names(opts)` reads them straight
    off the options, before anything is constructed, which is the whole reason
    it exists (`MqttPublisher` is built before the roster too). So the argument
    that could have graded that write was available at the call site the entire
    time, and the sibling function three screens down had already been fixed by
    passing it.

    ⚠️ SO NO CALLER PASSES `None` TODAY, and this branch is kept for one reason:
    it is what a NEW caller gets by DEFAULT. A future migration that forgets the
    roster gets the ungraded read-back and stamps its marker over a namespace no
    machine reads - silently, exactly as this one did. That is the shape of both
    defects, and the gap is recorded as a running check rather than left to a
    comment: test_maintenance.py section 13, and test_rehearse.py part 5, which
    drives it end-to-end through the harness an operator actually runs.
    """
    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 roster is None:
        return
    names = [str(n) for n in roster]
    # `unit_key()` builds `unit/<unit>/<key>`, so the unit is field 1. Split
    # through the same spelling the writer used rather than re-deriving it.
    #
    # ⚠️ `moved` UNION `kept`, AND THE UNION IS THE WHOLE OF THE SECOND FIX
    # ROUND. Grading only `moved` made the refusal last EXACTLY ONE START.
    # Measured at Controller level over one persisted store, roster
    # ["garage", "shed"], flat `last_completed` 2026-08-07, with the call site
    # still handing `inverter-a` on both starts:
    #
    #   construction 1: ok=False misdirected=4 moved=4 kept=0  marker=<absent>
    #   construction 2: ok=True  misdirected=0 moved=0 kept=4  marker=1
    #
    # On start 2 the four keys the WRONG start 1 wrote are already present, so
    # rule 1 routes every one of them to `rep.kept`, `rep.moved` is EMPTY, this
    # loop iterates over nothing, `misdirected` is empty and `ok` is True - so
    # the caller stamps the marker and start 3 takes the `from_version >=
    # SCHEMA` early return FOREVER, including after the call site is fixed.
    # Loud-and-recoverable became silent-and-permanent after one restart: the
    # exact state this module's header says must never happen, reached by the
    # fix that was written to prevent it.
    #
    # The union is sound by construction rather than by hope: every entry in
    # both `rep.moved` and `rep.kept` is a `unit_key(unit, legacy)` built from
    # the SAME `unit` argument, so grading `kept` grades the same namespace
    # decision `moved` does. A correct call site puts its `kept` entries under a
    # roster name and they pass; a wrong one cannot launder its namespace by
    # having already written it.
    for target in sorted(set(rep.moved) | set(rep.kept)):
        parts = target.split("/")
        unit = parts[1] if len(parts) > 2 else ""
        if unit in names:
            continue
        rep.verified = False
        note = (f"{target} was migrated into namespace {unit!r}, which is NOT "
                f"on the roster {names!r} - nothing reads that key")
        rep.problems.append(note)
        rep.misdirected.append(note)


def migrate_maint_keys(store, unit: str, roster) -> MigrationReport:
    """Move the flat maintenance history into the FIRST pack's namespace.

    MAINT-05. Until this card there was one `Maintenance` and one history, and
    `store.py`'s own header argued the keys should stay flat because per-pack
    scheduling was a card of its own. This is that card: there is now one FSM
    per roster entry, so there is one history per roster entry, and the flat one
    belongs to the pack that was being recalibrated - `inverters[0]`, which is
    what `Controller.maint_unit` named and what `validate.py` rule 6 graded
    against.

    ⚠️ `len(roster) <= 1` IS A RETURN, NOT A SPECIAL CASE. At one inverter the
    flat keys ARE that pack's namespace (§6.2's identity, the same one
    `arbiter.actuator_for()` leans on), `Maintenance` is constructed to read
    them directly, and a migration would add four keys plus a marker to a store
    that must come out byte-identical. The migration happens on the day the
    roster grows, which is the day the flat spelling stops being able to answer
    "which pack".

    ⚠️ `roster` IS REQUIRED, AND IT REPLACED AN `n_units: int`. Two reasons, and
    the second is the one MAINT-05 was rejected over.

    The small one: `n_units` was `len(self.inverters)` at the only call site, so
    the roster carries it - `len(roster)` - and a count passed beside the names
    is a second opinion about how many packs there are.

    The load-bearing one: THE NAMES ARE THE POSTCONDITION. `unit` says which
    pack the flat keys belonged to and that is genuinely a decision - the first
    roster entry, because that is the pack the one FSM was driving - but a
    decision the caller can get WRONG, and until this signature existed nothing
    could tell. `_verify_moves()` read back the namespace it was handed, so a
    migration into a name no machine reads verified clean and stamped the
    marker. Handing the roster in means the read-back is graded against the
    keys the MACHINES read, and a `unit` that is not among these names comes
    back `misdirected`: not `ok`, marker NOT written, migration runs again next
    start - and again the start after that, because `_verify_moves()` grades
    `kept` as well as `moved`. See `_verify_moves()` for the install this was
    measured on, and for what grading `moved` alone cost on start 2.

    THE THREE RULES ARE `migrate_unit_keys()`'s, SHARED IN CODE rather than
    restated: `_move_flat_keys()` is rule 1 (never overwrite a namespaced value)
    and rule 2 (the flat keys are left in the file), `_verify_moves()` is the
    read-back postcondition, and the marker is written LAST so a crash before it
    leaves the migration to run again - which rule 1 makes a no-op.

    ⚠️ AND RULE 2 IS KEPT LIVE HERE TOO, WHICH IS THE HALF DEV-02 HAD TO ADD
    LATER. "Left in place" alone makes the flat history a fossil dated the day
    the second inverter was declared: an operator who rolls back to a
    single-FSM add-on would find a `last_completed` months old and recalibrate a
    pack that does not need it, or - worse - a stale `phase` and a
    `phase_started` old enough to abort on the 12 h timeout the moment it comes
    up. So `maintenance.UnitHistory` MIRRORS the first pack's writes back onto
    the flat keys for as long as the roster has more than one entry. The flat
    pair is the ROLLBACK VIEW of the history, maintained, exactly as
    `sign_tripped` is the rollback view of the latch.
    """
    rep = MigrationReport()
    data = getattr(store, "data", {})
    names = [str(n) for n in roster]
    rep.from_version = int(data.get(MAINT_SCHEMA_KEY, 0) or 0)
    if len(names) <= 1:
        rep.skipped = ("one inverter: the flat maintenance keys ARE that pack's "
                       "history and are read in place, so there is nothing to "
                       "move and the store layout does not change")
        return rep
    if rep.from_version >= MAINT_SCHEMA_VERSION:
        rep.skipped = (f"maintenance history already at schema "
                       f"{rep.from_version}; written by a multi-inverter "
                       f"version and not touched")
        return rep

    rep.ran = True
    _move_flat_keys(store, unit, MAINT_UNIT_KEYS, rep)
    _verify_moves(store, rep, roster=names)

    # ⚠️ `rep.ok` AND NOTHING ELSE - NOT `ok or kept`, NOT `not lost`, NOT
    # `not misdirected`. BOTH guards gate this line and each one is pinned by a
    # check that the other cannot satisfy: section 9c refuses a store whose
    # failure is `misdirected` with `lost` empty, and section 9d refuses one
    # whose failure is `lost` with `misdirected` empty AND `kept` non-empty -
    # the mutation `if rep.ok or rep.kept:` stamps the marker on a migration
    # that lost a month of history, and until section 9d existed all 19 suites
    # were green on it.
    if rep.ok:
        store.set(MAINT_SCHEMA_KEY, MAINT_SCHEMA_VERSION)
    else:
        # ⚠️ NOT MARKED DONE, FOR EITHER FAILURE. The same sentence
        # `migrate_unit_keys()` carries: the one thing worse than a failed
        # migration is a failed migration a later version skips. Rule 1 makes
        # the re-run a no-op where the keys did land, so refusing the marker
        # costs one repeated pass and buys the difference between a migration
        # that can still be fixed and one the store says already happened.
        _LOG.error("per-pack maintenance-history migration did NOT land 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()