Merge remote-tracking branch 'origin/release/1.0' into TARIFF-11

# Conflicts:
#	goodwe_controller/CHANGELOG.md

goodwe_controller/app/tariff.py

@@ -132,6 +132,18 @@ OBSERVED = "observed"          # the store answered and there is a peak
 NO_RECORD = "no_record"        # the store answered and this month has none yet
 NOT_OBSERVED = "not_observed"  # the store did not answer. NOT a zero peak.
 
+# TARIFF-13. What the COVERAGE figure reads when the store cannot count.
+#
+# ⚠️ NOT 0, AND NOT `None`. This is the reading-state argument of TARIFF-01
+# applied to the number printed BESIDE the peak rather than to the peak. A
+# coverage figure of 0 says "this month has been measured over no quarters at
+# all", which is the strongest possible claim that the peak next to it means
+# nothing - and `f"{None} quarter(s) banked"` renders "None quarter(s) banked",
+# which an operator reads as that same zero. The one honest answer to "how many
+# quarters have I banked" when the table will not answer is that it is not
+# known, and it has to SAY so in the sentence the operator reads.
+COUNT_UNREADABLE = "an unreadable number of"
+
 
 # --------------------------------------------------------------------------- #
 # local time, without a hard dependency on the tz database
@@ -388,6 +400,23 @@ class PeakStore:
                     "   per_phase_json=excluded.per_phase_json"
                     " WHERE excluded.offtake_avg_w > quarter_blocks.offtake_avg_w",
                     (start, month, w, pp_json))
+                # TARIFF-13. THE TIE RULE, DECIDED RATHER THAN EMERGENT:
+                # at EQUAL wattage the EARLIEST quarter keeps the attribution.
+                # See DECISIONS/TARIFF-13-the-coverage-of-a-peak.md §2.
+                #
+                # `peak_w` itself is still only ever RAISED - the `>` term is
+                # untouched and no tie can move the billed number - so SAFETY-07
+                # reads exactly the watt figure it read before. The second term
+                # moves only the TIMESTAMP the status page attributes it to.
+                #
+                # ⚠️ WITHOUT THE SECOND TERM THE TWO READERS DISAGREE, measured:
+                # `>` alone keeps whichever tied block was WRITTEN FIRST, while
+                # `recompute_month()`'s `ORDER BY offtake_avg_w DESC,
+                # quarter_start ASC` keeps the EARLIEST. Those coincide only
+                # while blocks arrive in time order. Fed four equal 365 W blocks
+                # newest-first, `monthly_peak` answered 09:45 and the recompute
+                # answered 09:00 - a divergence in the derived record part 8 of
+                # test_tariff.py exists to prove cannot happen.
                 self._db.execute(
                     "INSERT INTO monthly_peak(month, peak_w, quarter_start, per_phase_json)"
                     " VALUES(?,?,?,?)"
@@ -395,7 +424,9 @@ class PeakStore:
                     "   peak_w=excluded.peak_w,"
                     "   quarter_start=excluded.quarter_start,"
                     "   per_phase_json=excluded.per_phase_json"
-                    " WHERE excluded.peak_w > monthly_peak.peak_w",
+                    " WHERE excluded.peak_w > monthly_peak.peak_w"
+                    "    OR (excluded.peak_w = monthly_peak.peak_w"
+                    "        AND excluded.quarter_start < monthly_peak.quarter_start)",
                     (month, w, start, pp_json))
             return True
         except sqlite3.Error as err:
@@ -449,6 +480,49 @@ class PeakStore:
                            quarter_start=datetime.fromisoformat(row[1]),
                            per_phase_w=pp)
 
+    def banked_count(self, month: str) -> int | None:
+        """How many quarters this month has banked. `None` when unknowable.
+
+        TARIFF-13. THE DEFECT THIS PREVENTS: the status page printed a coverage
+        figure held in PROCESS MEMORY - `PeakTracker.recorded`, incremented once
+        per block banked by THIS process - beside a peak read from SQLite. The
+        peak outlives a restart and the counter does not, so a driven restart
+        mid-month took a real reading of
+
+            2026-09: peak 365 W ... ; 120 quarter(s) banked
+
+        to the same peak, the same attributed quarter and `0 quarter(s) banked`,
+        on both instances independently. The count is what tells an operator how
+        much of the billing month the number beside it actually covers: 365 W
+        over 120 quarters and 365 W over 0 quarters are different claims about
+        the same watt figure, and after a restart the page made the weaker claim
+        while displaying the stronger one's value. Reading the count from the
+        same durable tier the peak comes from is what makes the two agree.
+
+        ⚠️ `None`, NOT 0, and NOT `len(blocks_in(month))`. `blocks_in()` returns
+        `[]` on a read error - safe there only because no caller reads its
+        emptiness as a peak (§ its own docstring) - so counting its length would
+        rebuild the disarming zero one call further out. This asks the database
+        for a COUNT and refuses to answer when the database refuses.
+
+        ⚠️ Counts `quarter_blocks`, the tier with one row per closed block, and
+        NOT `monthly_peak`, which has one row per MONTH and would answer 1 for
+        every month that has ever been measured. The two tables are proven equal
+        on the PEAK by `recompute_month()`; they were never equal on the COUNT
+        and are not meant to be.
+        """
+        if self._db is None:
+            return None
+        try:
+            row = self._db.execute(
+                "SELECT COUNT(*) FROM quarter_blocks WHERE month=?",
+                (month,)).fetchone()
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            _LOG.error("could not count quarters for %s (%s)", month, err)
+            return None
+        return int(row[0])
+
     def blocks_in(self, month: str) -> list:
         """(quarter_start, offtake_avg_w) for a month, oldest first. [] on error
         is safe here ONLY because no caller reads emptiness as a peak - AC 3's
@@ -539,11 +613,59 @@ class PeakTracker:
         self.cap_w = float(cap_w)
         self.policy = policy
         self.checkpoint_s = float(checkpoint_s)
-        self.recorded = 0
         self.restore_state = "not attempted"
         self._seen: set = set()
         self._last_ckpt = 0.0
 
+    # -- coverage -----------------------------------------------------------
+    #
+    # TARIFF-13. `recorded` USED TO BE AN `int` ATTRIBUTE ON THIS OBJECT,
+    # starting at 0 and incremented in `sync()`. It is a property over the store
+    # now, and the three things that changes are all defects it was carrying:
+    #
+    #   * it RESET TO 0 ON EVERY RESTART, beside a peak that did not - see
+    #     `PeakStore.banked_count()` for the driven reading;
+    #   * it was NOT SCOPED TO A MONTH. It counted every block this process had
+    #     banked, so on 1 October the row still read September's tally beside
+    #     October's "no completed quarter recorded yet";
+    #   * it MISSED the block `restore()` banks. A stale block closed from the
+    #     checkpoint goes into `quarter_blocks` and never went through `sync()`,
+    #     so the counter never saw it. Counting the table cannot miss it.
+    #
+    # ⚠️ REMOVING THE COUNTER DOES NOT REMOVE THE DEDUPE. `_seen` is still what
+    # stops `cycle()`'s once-a-second `sync()` re-banking a closed quarter that
+    # `P1Ingest.blocks` keeps for a DAY, and `sync()`'s RETURN value is still
+    # the count of blocks newly banked on that call. What changed is only where
+    # the STATUS PAGE's figure is read from. The check that grades the dedupe
+    # must therefore grade `sync()`'s return, not this property, which now
+    # answers 1 from the database however many times the block was offered.
+
+    def recorded_in(self, when: datetime | None = None):
+        """Quarters banked in `when`'s billing month - `int`, or the sentinel.
+
+        ⚠️ The return type is `int | str` on purpose, and the `str` is
+        `COUNT_UNREADABLE`. A caller that formats this into a sentence gets a
+        true sentence in both cases; a caller that wants to do arithmetic on it
+        gets a TypeError, which is loud. That is the same trade `PeakReading`
+        makes by having no `peak_w_or(default)`.
+        """
+        n = self.store.banked_count(month_key(when or datetime.now(timezone.utc)))
+        return COUNT_UNREADABLE if n is None else n
+
+    @property
+    def recorded(self):
+        """Quarters banked in the month being billed TODAY.
+
+        ⚠️ This is the live status page's reading, where the peak beside it is
+        also read for `datetime.now()`. `checks(when=X)` for an X in another
+        month is a test affordance (TEST-17); the row scoped that way gets this
+        month's count beside that month's peak, which is strictly better than
+        the process-wide counter it replaces but is still a mismatch.
+        `recorded_in(when)` is the scoped form the row should read once
+        `main.py`'s status rows are free to change - TARIFF-11 holds them.
+        """
+        return self.recorded_in()
+
     # -- startup ------------------------------------------------------------
     def restore(self, averager, now: datetime | None = None) -> str:
         """Put the open block back. Returns which of the three cases happened."""
@@ -600,7 +722,6 @@ class PeakTracker:
                 continue
             if self.store.record_block(block, self.policy):
                 self._seen.add(key)
-                self.recorded += 1
                 n += 1
         if n:
             # A block just closed, so the checkpoint's block is gone: clearing it