tariffkit 0.4.0__tar.gz → 0.5.0__tar.gz

{tariffkit-0.4.0 → tariffkit-0.5.0}/CHANGELOG.md

@@ -5,6 +5,83 @@ All notable changes to this project are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-29
+
+### Added
+- The Amount Due entities and the backfill response publish the terms their
+  breakdown rests on. `gross_charges` is the ledger's own charge total,
+  `non_offsettable` the part of it no credit may reach, and `not_paid_out` the
+  clamp a statement applies rather than refunding. Together
+  `gross_charges - credit_applied + not_paid_out` is the state exactly, for a
+  day and for a cycle.
+
+  The published components could not be added into the state before this. A
+  component the statement spends inside the cycle rather than banking -- MCE's
+  Solar Bonus Credit is the one vendored -- is subtracted from the charges
+  before credits are applied and appeared in no attribute: not in
+  `export_credits`, not in `credit_applied`. A consumer summing what was there
+  landed short by exactly that, with no way to tell a missing term from a
+  rounding error.
+
+### Fixed
+- The backfill coverage check no longer reports an hour it refused as an hour
+  the recorder lost. An hour falls outside the priced set for three reasons and
+  only one of them is absence: no statistics row, no usable total on the row,
+  or a change refused as a counter's catch-up across an outage. All three
+  printed as "is missing N of M hour(s)", which reads as data loss -- on a
+  window whose 1392 hours were all on disk it claimed 299 were gone. What the
+  recorder held and what could be priced are now counted apart and reported in
+  their own words.
+
+## [0.4.1] - 2026-08-27
+
+### Fixed
+- A CCA that credits an ACC Plus adder of its own is now paid for it. The adder
+  is credited **twice** on such an account, once by each party at the same
+  $/kWh, and only the utility's half was modelled -- so `export_price.total`
+  understated a CCA export by the adder, and the CCA's credit bank was short by
+  its entire balance.
+
+  The two halves do not behave alike, which is why they are now separate
+  buckets rather than one. The utility earns its half and spends it against
+  delivery charges in the same cycle: on the 2026-08-04 statement PG&E's bank
+  prints Bonus Credits earned $1.71, applied -$1.71, remaining $0.00. MCE earns
+  its own $1.70 in that cycle and applies none of it -- its "Energy Export Bonus
+  Credits Applied" line prints $0.00 -- so its EEBC balance reaches $3.29, being
+  June's $1.59 plus July's $1.70 with nothing taken out. Folding both into one
+  bonus bucket let the utility's spending drain a balance the statement shows
+  growing, and reported the CCA's bank $3.29 light on a $12.63 balance.
+
+  A new `cca_acc_plus` export component carries it, `CreditBucket.CCA_BONUS`
+  banks it, and it is spent only after the CCA's export credit is exhausted --
+  the order the statement's own applied figures imply. Providers declare it
+  with `credits_acc_plus` in their rate card, defaulting to false, so no
+  provider is credited an adder no statement has shown them paying. Only MCE's
+  card sets it.
+
+  No reconciled bill caught this and none could: the audit compares printed
+  charges against computed ones, and a credit that is never applied never
+  reaches a charge. It was found by folding a real meter series against the
+  statement's printed balances instead of its charges.
+
+  The audit map keeps up with it: the earned component is declared as one the
+  statement does not print separately, and the CCA's grouped "Energy Export
+  Credits Applied" rule now sums the bonus applied alongside the export credit
+  applied, as the two printed lines it already reads do. Both were needed for
+  `audit reconcile` to keep passing -- without the first it reported an unmapped
+  component on every MCE cycle, and without the second it would have reported a
+  mismatch on the first correct bill that spends the bonus.
+
+  `month_curve` plots the export price again. It had been the delivery
+  component plus the ACC Plus adders on a CCA account, omitting the CCA's
+  generation credit and its bonuses -- a figure neither party pays. It and
+  `price_at` are now built from one component rule instead of two copies of it.
+
+  **Export prices change for CCA accounts**, by the ACC Plus rate --
+  $0.00880/kWh for a 2026 residential interconnection. Forecasts, the MQTT
+  payloads, and the EMHASS and Predbat attributes all carry the higher figure,
+  because it is what the two statements between them actually credit.
+
 ## [0.4.0] - 2026-08-26
 
 ### Added
@@ -477,7 +554,9 @@ Initial release.
 - Holiday calendars are extracted per vintage from the source data rather than
   recomputed, because the vintage files disagree in far-future years.
 
-[Unreleased]: https://github.com/eman/tariffkit/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/eman/tariffkit/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/eman/tariffkit/releases/tag/v0.5.0
+[0.4.1]: https://github.com/eman/tariffkit/releases/tag/v0.4.1
 [0.4.0]: https://github.com/eman/tariffkit/releases/tag/v0.4.0
 [0.3.0]: https://github.com/eman/tariffkit/releases/tag/v0.3.0
 [0.2.3]: https://github.com/eman/tariffkit/releases/tag/v0.2.3

{tariffkit-0.4.0 → tariffkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tariffkit
-Version: 0.4.0
+Version: 0.5.0
 Summary: Offline electricity tariff pricing, billing, and integration tools
 Project-URL: Homepage, https://github.com/eman/tariffkit
 Project-URL: Documentation, https://github.com/eman/tariffkit#documentation

{tariffkit-0.4.0 → tariffkit-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tariffkit"
-version = "0.4.0"
+version = "0.5.0"
 description = "Offline electricity tariff pricing, billing, and integration tools"
 readme = "README.md"
 license = "MIT"

{tariffkit-0.4.0 → tariffkit-0.5.0}/src/tariffkit/billing/ledger.py

@@ -10,8 +10,10 @@ Credits are not fungible. PG&E's statement states the rule directly:
     2. Energy Delivered credits can only offset Energy Delivered charges
     3. Energy Export Bonus Credit can offset any and all electric charges
 
-So a balance is three buckets, not a number, and applying it needs each charge
-classified by which bucket may offset it.
+So a balance is four buckets, not a number, and applying it needs each charge
+classified by which bucket may offset it. Four rather than three because a CCA
+account is credited the ACC Plus adder twice -- the utility's half is spent
+where it is earned, the CCA's half banks on the CCA's own page.
 
 **One bank at a time.** A CCA customer has two, kept separately: PG&E's and the
 CCA's, each with its own balance and its own charges to offset. A :class:`Bill`
@@ -46,20 +48,40 @@ class CreditBucket(StrEnum):
     DELIVERY = "delivery"
     #: Offsets anything not explicitly non-bypassable.
     BONUS = "bonus"
+    #: The generation supplier's own bonus credit, banked on its page and
+    #: settled on its calendar. The ACC Plus adder is credited twice on a CCA
+    #: account -- see ``CREDIT_BUCKETS`` -- and the two halves are not one
+    #: bucket: the utility spends its half against delivery charges in the
+    #: cycle that earns it, while this one accumulates untouched.
+    CCA_BONUS = "cca_bonus"
 
 
 #: Export credit component -> the bucket it banks into.
 #:
-#: Verified against the 2026-08-04 statement, whose credit bank splits into
-#: "Energy Delivered Credits" $6.25 (the ``delivery`` component) and "Bonus
-#: Credits" $1.71 (``acc_plus``), and whose CCA page reports an Energy Export
-#: Credit of $9.63 (``cca_generation``).
+#: Verified against the 2026-08-04 statement. Its two credit banks print:
 #:
+#:   PG&E "YOUR ENERGY EXPORT CREDIT BANK"
+#:     Energy Delivered Credits  earned $6.25, applied -$6.25, remaining $0.00
+#:     Bonus Credits             earned $1.71, applied -$1.71, remaining $0.00
+#:   MCE
+#:     Solar Export Credits (EEC) earned this cycle        $9.63
+#:     Solar Export Bonus Credits (EEBC) earned this cycle  $1.70
+#:     Current EEC Balance $9.34, Current EEBC Balance $3.29, SBP total $12.63
+#:
+#: The ACC Plus adder is therefore credited TWICE, once by each party at the
+#: same $/kWh: the utility earns and spends its half inside the cycle, and the
+#: CCA banks its own half without ever applying it -- MCE's "Energy Export
+#: Bonus Credits Applied" line prints $0.00 while its EEBC balance grows by the
+#: full amount every cycle ($1.59 in June plus $1.70 in July gives the printed
+#: $3.29). Modelling one adder understated the CCA's bank by its whole balance
+#: and no reconciled bill noticed, because a credit that is never applied never
+#: reaches a charge the audit compares.
 CREDIT_BUCKETS: dict[str, CreditBucket] = {
     "delivery": CreditBucket.DELIVERY,
     "generation": CreditBucket.GENERATION,
     "cca_generation": CreditBucket.GENERATION,
     "acc_plus": CreditBucket.BONUS,
+    "cca_acc_plus": CreditBucket.CCA_BONUS,
 }
 
 #: Export-side components a statement spends inside the cycle instead of banking.
@@ -132,10 +154,12 @@ SCOPING_VERIFIED = False
 #: Which buckets each party's bank holds when a CCA supplies generation.
 #:
 #: PG&E's "Energy Delivered Credits" and "Bonus Credits" against the CCA's
-#: "Energy Export Credit". They settle on unrelated calendars -- PG&E at the
-#: Permission To Operate anniversary, the CCA on its own cash-out year.
+#: "Energy Export Credit" and its own bonus credit -- MCE prints the latter two
+#: as the EEC and EEBC balances that sum to the SBP balance. They settle on
+#: unrelated calendars -- PG&E at the Permission To Operate anniversary, the CCA
+#: on its own cash-out year.
 UTILITY_BUCKETS = (CreditBucket.DELIVERY, CreditBucket.BONUS)
-GENERATION_BUCKETS = (CreditBucket.GENERATION,)
+GENERATION_BUCKETS = (CreditBucket.GENERATION, CreditBucket.CCA_BONUS)
 
 
 @dataclass(frozen=True, slots=True)
@@ -145,6 +169,7 @@ class CreditBalances:
     generation: float = 0.0
     delivery: float = 0.0
     bonus: float = 0.0
+    cca_bonus: float = 0.0
 
     def __post_init__(self) -> None:
         for bucket in CreditBucket:
@@ -159,7 +184,7 @@ class CreditBalances:
 
     @property
     def total(self) -> float:
-        return self.generation + self.delivery + self.bonus
+        return self.generation + self.delivery + self.bonus + self.cca_bonus
 
     def held_by(self, party: str, *, split: bool) -> float:
         """The balance one party holds.
@@ -188,6 +213,7 @@ class CreditBalances:
             "generation": round(self.generation, 4),
             "delivery": round(self.delivery, 4),
             "bonus": round(self.bonus, 4),
+            "cca_bonus": round(self.cca_bonus, 4),
             "total": round(self.total, 4),
         }
 
@@ -248,6 +274,7 @@ def credits_earned(bill: Bill) -> CreditBalances:
         generation=totals[CreditBucket.GENERATION],
         delivery=totals[CreditBucket.DELIVERY],
         bonus=totals[CreditBucket.BONUS],
+        cca_bonus=totals[CreditBucket.CCA_BONUS],
     )
 
 
@@ -322,6 +349,7 @@ def apply_credits(bill: Bill, opening: CreditBalances | None = None) -> LedgerEn
         generation=opening.generation + earned.generation,
         delivery=opening.delivery + earned.delivery,
         bonus=opening.bonus + earned.bonus,
+        cca_bonus=opening.cca_bonus + earned.cca_bonus,
     )
     applied = CreditBalances()
     remaining = dict(offsettable)
@@ -331,6 +359,15 @@ def apply_credits(bill: Bill, opening: CreditBalances | None = None) -> LedgerEn
         applied = applied.with_bucket(bucket, spend)
         remaining[bucket] -= spend
 
+    # The CCA's bonus reaches its own generation charges, and only after its
+    # export credit has. That order is the statement's, not a preference: on
+    # 2026-08-04 MCE applied $3.63 of Energy Export Credit and $0.00 of Energy
+    # Export Bonus Credit against the same $3.63 of net generation charges.
+    # Spending it first would drain the bank that the statement shows growing.
+    cca_bonus_spend = min(available.cca_bonus, remaining[CreditBucket.GENERATION])
+    applied = applied.with_bucket(CreditBucket.CCA_BONUS, cca_bonus_spend)
+    remaining[CreditBucket.GENERATION] -= cca_bonus_spend
+
     # The bonus reaches anything still standing, except charges the tariff makes
     # non-bypassable -- that is what "non-bypassable" means.
     bonus_spend = min(available.bonus, sum(remaining.values()))
@@ -340,6 +377,7 @@ def apply_credits(bill: Bill, opening: CreditBalances | None = None) -> LedgerEn
         generation=available.generation - applied.generation,
         delivery=available.delivery - applied.delivery,
         bonus=available.bonus - applied.bonus,
+        cca_bonus=available.cca_bonus - applied.cca_bonus,
     )
     gross = sum(offsettable.values()) + non_offsettable
     # A statement charges nothing rather than paying out. `non_offsettable` can
@@ -355,6 +393,7 @@ def apply_credits(bill: Bill, opening: CreditBalances | None = None) -> LedgerEn
             generation=available.generation - applied.generation,
             delivery=available.delivery - applied.delivery,
             bonus=available.bonus - applied.bonus,
+            cca_bonus=available.cca_bonus - applied.cca_bonus,
         )
     return LedgerEntry(
         period=bill.period,
@@ -373,12 +412,21 @@ def apply_credits(bill: Bill, opening: CreditBalances | None = None) -> LedgerEn
 def _reduce(applied: CreditBalances, by: float) -> CreditBalances:
     """Un-spend ``by`` dollars of credit, bonus first.
 
-    Reverse of the order it was spent in: the bonus is the most widely usable
-    bucket, so it is the one to hand back when the charges turn out not to have
-    needed it.
+    Reverse of the order it was spent in, exactly: the bonus is the most widely
+    usable bucket, so it is the one to hand back when the charges turn out not
+    to have needed it, and the CCA's bonus is next because it is spent last of
+    the scoped buckets. Handing back a scoped bucket ahead of one spent after it
+    moves credit between the two banks -- returning delivery credit to the
+    utility while leaving the CCA's bonus spent is the misattribution
+    ``CCA_BONUS`` exists to prevent.
     """
     left = by
-    for bucket in (CreditBucket.BONUS, CreditBucket.DELIVERY, CreditBucket.GENERATION):
+    for bucket in (
+        CreditBucket.BONUS,
+        CreditBucket.CCA_BONUS,
+        CreditBucket.DELIVERY,
+        CreditBucket.GENERATION,
+    ):
         give = min(applied[bucket], left)
         applied = applied.with_bucket(bucket, applied[bucket] - give)
         left -= give

{tariffkit-0.4.0 → tariffkit-0.5.0}/src/tariffkit/cca.py

@@ -93,6 +93,18 @@ class CcaRateCard:
         """Whether this provider's export credit basis has been confirmed."""
         return bool(self.raw.get("export", {}).get("export_credit_verified", False))
 
+    @property
+    def credits_acc_plus(self) -> bool:
+        """Whether this provider credits the ACC Plus adder in its own right.
+
+        The utility credits it too, on its own page and at the same rate, so a
+        provider that does this pays the customer a second adder rather than a
+        share of one. Default false: crediting an adder nobody pays is an
+        invented credit, which is the class of defect the audit exists to
+        catch, so a provider claims this only once a statement has shown it.
+        """
+        return bool(self.raw.get("export", {}).get("credits_acc_plus", False))
+
 
 @lru_cache(maxsize=8)
 def load_rate_card(provider: str, on: date) -> CcaRateCard:

{tariffkit-0.4.0 → tariffkit-0.5.0}/src/tariffkit/components.py

@@ -139,6 +139,7 @@ COMPONENT_GROUPS: dict[str, ComponentGroup] = {
     # Discounts and incentives.
     "medical_discount": ComponentGroup.CREDITS,
     "acc_plus": ComponentGroup.CREDITS,
+    "cca_acc_plus": ComponentGroup.CREDITS,
     # Bill-level components. A marginal price never carries these -- a baseline
     # credit depends on cumulative usage, and a tax on a whole cycle's charges
     # -- but ``group_of`` is public, so a caller grouping a ``Bill``'s

{tariffkit-0.4.0 → tariffkit-0.5.0}/src/tariffkit/data/cca/mce/2026-04-01.toml

@@ -150,3 +150,16 @@ care_fera_bonus_through = "2028-12-31"
 # and 193 kWh spread across all three TOU periods is a fair test of that.
 export_credit_basis = "acc_generation"
 export_credit_verified = true
+
+# MCE credits an ACC Plus adder of its OWN, additional to PG&E's, at the same
+# $/kWh -- it banks as the Energy Export Bonus Credit (EEBC) and is settled on
+# MCE's Solar Billing Plan year rather than PG&E's True-Up.
+#
+# Read from the 2026-08-04 statement, which prints both in the same cycle:
+# PG&E's page applies -$1.71 of "Energy Export Bonus Credits" and closes its
+# Bonus Credits bank at $0.00, while MCE's page reports "Solar Export Bonus
+# Credits (EEBC) earned this cycle $1.70" and a "Current EEBC Balance" of
+# $3.29 -- June's $1.59 plus July's $1.70, nothing applied. MCE's own "Energy
+# Export Bonus Credits Applied" line prints $0.00 in the same cycle, so the
+# balance is not PG&E's adder shown twice; it is a second one.
+credits_acc_plus = true

{tariffkit-0.4.0 → tariffkit-0.5.0}/src/tariffkit/export/nbt.py

@@ -140,8 +140,30 @@ class NbtExportRates:
         day_index = 0 if kind is DayType.WEEKDAY else 1
         hour = export_hour(moment)
 
-        delivery = float(data["delivery"][month_index][day_index][hour])
-        components: dict[str, float] = {"delivery": delivery}
+        components, complete = self._components(data, month_index, day_index, hour, moment.date())
+        return ExportPrice(
+            total=round(sum(components.values()), 6),
+            vintage=self.vintage,
+            day_type=kind,
+            components={k: round(v, 6) for k, v in components.items()},
+            locked=self.is_locked(moment),
+            complete=complete,
+            exact=moment.year <= self.exact_through,
+        )
+
+    def _components(
+        self, data: dict[str, Any], month_index: int, day_index: int, hour: int, on: date
+    ) -> tuple[dict[str, float], bool]:
+        """One hour's export credit components, and whether they are verified.
+
+        Shared with ``month_curve`` rather than duplicated into it. The two had
+        drifted -- the curve was the delivery component plus adders on a CCA
+        account, a figure neither party pays -- and a second copy of a rule this
+        fiddly is a second place for it to go wrong.
+        """
+        components: dict[str, float] = {
+            "delivery": float(data["delivery"][month_index][day_index][hour])
+        }
         complete = True
 
         if self.config.supplier is Supplier.BUNDLED:
@@ -163,7 +185,7 @@ class NbtExportRates:
                 # MCE's is reconciled against a real cycle, others are estimates.
                 from ..cca import load_rate_card
 
-                card = load_rate_card(cca.rate_card, moment.date())
+                card = load_rate_card(cca.rate_card, on)
                 components["cca_generation"] = float(
                     data["generation"][month_index][day_index][hour]
                 )
@@ -171,36 +193,38 @@ class NbtExportRates:
                     components["cca_solar_bonus"] = (
                         components["cca_generation"] * card.solar_bonus_fraction
                     )
+                if card.credits_acc_plus and self._acc_plus:
+                    # A second ACC Plus adder, not a share of the utility's.
+                    # MCE credits its own at the same $/kWh and banks it as the
+                    # Energy Export Bonus Credit; the 2026-08-04 statement
+                    # prints both, $1.71 applied on PG&E's page and $1.70 added
+                    # to MCE's EEBC balance in the same cycle.
+                    components["cca_acc_plus"] = self._acc_plus
                 complete = card.export_credit_verified
             else:
                 complete = False
 
         if self._acc_plus:
             components["acc_plus"] = self._acc_plus
-
-        return ExportPrice(
-            total=round(sum(components.values()), 6),
-            vintage=self.vintage,
-            day_type=kind,
-            components={k: round(v, 6) for k, v in components.items()},
-            locked=self.is_locked(moment),
-            complete=complete,
-            exact=moment.year <= self.exact_through,
-        )
+        return components, complete
 
     def month_curve(self, year: int, month: str, kind: DayType) -> tuple[float, ...]:
-        """The 24 hourly totals for one month and day type -- handy for plots."""
+        """The 24 hourly totals for one month and day type -- handy for plots.
+
+        Each hour is what ``price_at`` totals for it, CCA generation and both
+        bonus credits included, so a plotted curve is the export price rather
+        than a subset of it. The card is read for the first of the month, which
+        is the same card ``price_at`` reads for any hour it contains.
+        """
         data = self._payload["data"].get(str(year))
         if data is None:
             low, high = self.covered_years
             raise OutOfRangeError(f"{self.vintage}: {year} outside {low}-{high}")
         month_index = MONTHS.index(month)
         day_index = 0 if kind is DayType.WEEKDAY else 1
-        generation = data["generation"][month_index][day_index]
-        delivery = data["delivery"][month_index][day_index]
-        include_generation = self.config.supplier is Supplier.BUNDLED
+        on = date(year, month_index + 1, 1)
         return tuple(
-            round((generation[h] if include_generation else 0.0) + delivery[h] + self._acc_plus, 6)
+            round(sum(self._components(data, month_index, day_index, h, on)[0].values()), 6)
             for h in range(24)
         )
 

{tariffkit-0.4.0 → tariffkit-0.5.0}/tests/test_export_golden.py

@@ -99,3 +99,38 @@ def test_lock_window_falls_inside_the_exactly_verified_range() -> None:
     lock_end = config.lock_end
     assert lock_end is not None
     assert lock_end.year <= rates.exact_through
+
+
+@pytest.mark.parametrize("supplier", ["bundled", "cca"])
+def test_the_month_curve_is_the_price_it_plots(supplier: str) -> None:
+    """Each hour of the curve equals what ``price_at`` totals for that hour.
+
+    Untested until now, and it had drifted: on a CCA account the curve was the
+    delivery component plus the ACC Plus adders, omitting the CCA's generation
+    credit and its bonuses -- a figure neither party pays, plotted as though it
+    were the export price. Both are built from one component rule now, and this
+    is what says they still are.
+    """
+    from datetime import date
+
+    from tariffkit.config import CcaConfig
+    from tariffkit.models import Supplier
+
+    config = (
+        Config(
+            tariff="E-ELEC",
+            supplier=Supplier.CCA,
+            cca=CcaConfig(name="MCE", rate_card="mce"),
+            interconnection_year=2026,
+            pto_date=date(2026, 1, 1),
+        )
+        if supplier == "cca"
+        else Config()
+    )
+    rates = NbtExportRates(config)
+    curve = rates.month_curve(2026, "Jul", DayType.WEEKDAY)
+    # 2026-07-15 is a Wednesday, so every hour of it is a weekday hour.
+    hourly = [
+        rates.price_at(datetime(2026, 7, 15, hour, tzinfo=PACIFIC)).total for hour in range(24)
+    ]
+    assert list(curve) == pytest.approx(hourly)

{tariffkit-0.4.0 → tariffkit-0.5.0}/tests/test_ha_backfill.py

@@ -888,3 +888,81 @@ def test_a_settlement_lowers_what_the_cycles_after_it_can_offset() -> None:
     after = [e for e in result.lifetime.entries if e.period.start > settled]
     assert before and after
     assert after[0].opening.total < before[-1].closing.total, "the clawback reached the next cycle"
+
+
+def test_a_recorded_hour_this_refuses_is_not_reported_as_missing() -> None:
+    """An hour the recorder wrote is not an hour the recorder lost.
+
+    The coverage warning counted every hour absent from `covered`, and an hour
+    whose counter jumped further than a house can draw is refused rather than
+    absent. Reporting it as missing told an owner their meter history had holes
+    in it when every hour was on disk.
+    """
+    import asyncio
+    from datetime import datetime, timedelta
+
+    from custom_components.tariffkit.energy import MeterSettings, UsageReader
+
+    from tariffkit.timeutil import PACIFIC
+
+    def warnings_for(*, refuse: bool) -> tuple[str, ...]:
+        reader = UsageReader(None, MeterSettings(import_entity="sensor.x"))  # type: ignore[arg-type]
+        opens = datetime(2026, 6, 1, tzinfo=PACIFIC)
+        rows: list[dict[str, float]] = []
+        total = 0.0
+        for index in range(73):
+            hole = bool(index) and index % 6 == 0
+            if hole and not refuse:
+                continue  # the recorder never wrote this hour
+            total += 500.0 if hole else 0.5
+            rows.append(
+                {"start": (opens - timedelta(hours=1)).timestamp() + index * 3600, "sum": total}
+                | {"change": 500.0 if hole else 0.5, "state": total}
+            )
+
+        async def query(window: datetime, until: datetime) -> dict[str, list[dict[str, float]]]:
+            del window, until
+            return {"sensor.x": rows}
+
+        reader._async_query = query  # type: ignore[method-assign]
+        asyncio.run(reader.async_readings(date(2026, 6, 1), date(2026, 6, 3)))
+        return reader.absent
+
+    refused = warnings_for(refuse=True)
+    assert len(refused) == 1
+    assert "could not use" in refused[0]
+    assert "is missing" not in refused[0], "every hour was on disk"
+
+    # The genuine hole still reads as one, in the same words as before.
+    absent = warnings_for(refuse=False)
+    assert absent == ("sensor.x is missing 12 of 72 hour(s) in this window",)
+
+
+def test_the_summary_cycles_carry_the_terms_that_reconcile_them() -> None:
+    """The payload has to add up for the same reason the entity attributes do.
+
+    `cash_due` is `max(0, gross_charges - credit_applied)`, so a consumer given
+    only the charge components lands short of it by whatever the statement spent
+    in-cycle instead of banking. Both terms are published; this is what notices
+    if either stops being.
+    """
+    profile = _profile()
+    readings = _hours(date(2026, 6, 1), date(2026, 7, 31), imported=0.2, exported=2.0)
+    result = backfill.build(profile, readings, date(2026, 6, 1), date(2026, 7, 31), 1)
+    from tariffkit.billing import run_ledger
+
+    entries = {entry.period: entry for entry in run_ledger(result.bills).entries}
+
+    cycles = result.summary("probe")["cycles"]
+    assert len(cycles) == 2
+    for cycle in cycles:
+        entry = entries[
+            next(b.period for b in result.bills if b.period.start.isoformat() == cycle["start"])
+        ]
+        assert cycle["gross_charges"] == pytest.approx(round(entry.gross_charges, 2))
+        assert cycle["non_offsettable"] == pytest.approx(round(entry.non_offsettable, 2))
+        # Each term is rounded to cents independently, so the identity over the
+        # payload cannot hold tighter than the three roundings it carries.
+        assert cycle["cash_due"] == pytest.approx(
+            max(0.0, cycle["gross_charges"] - cycle["credit_applied"]), abs=0.02
+        )

{tariffkit-0.4.0 → tariffkit-0.5.0}/tests/test_ha_bank.py

@@ -139,9 +139,10 @@ def test_a_cca_account_holds_two_banks_that_never_settle_together() -> None:
     """A statement prints them on separate pages, on unrelated calendars.
 
     PG&E keeps "Energy Delivered Credits" and "Bonus Credits"; the CCA keeps its
-    "Energy Export Credit". PG&E settles at the Permission To Operate
-    anniversary and the CCA on its own cash-out year, so a single total is a
-    figure no statement shows and that never settles as a whole.
+    "Energy Export Credit" and its own bonus credit. PG&E settles at the
+    Permission To Operate anniversary and the CCA on its own cash-out year, so a
+    single total is a figure no statement shows and that never settles as a
+    whole.
     """
     profile = _cca_profile()
     bills = [
@@ -154,7 +155,7 @@ def test_a_cca_account_holds_two_banks_that_never_settle_together() -> None:
     utility = state.held_by("utility")
     generation = state.held_by("generation")
     assert utility == pytest.approx(state.balance.delivery + state.balance.bonus)
-    assert generation == pytest.approx(state.balance.generation)
+    assert generation == pytest.approx(state.balance.generation + state.balance.cca_bonus)
     assert utility + generation == pytest.approx(state.balance.total)
     # Neither alone is the whole bank, which is the point.
     assert utility != pytest.approx(state.balance.total)