goodwe-addon/goodwe_controller/DECISIONS/SAFETY-37-freshness-policy.md

# SAFETY-37 — the freshness policy, and the one sentence in the card that had to be rewritten

**Status: DECIDED 2026-09-06.** A per-unit reading that has stopped following its
own command is reported to its consumers as **`None`**, never as a held number.
The verdict is a **conjunction**, not an age threshold, and this document records
why an age threshold is not available at this layer — which is the one place the
card's wording could not be implemented as written.

Filed with SAFETY-37. Card `6a9a7eda7932387c3acbd700`, scope widened by the
architect pass of 2026-09-06 to carry the single policy for [[TEL-06]] and
[[TEL-08]] as well.

Every figure below was measured or read out of this repository on **2026-09-06**
and is re-derived by `test_freshness.py` on every run. Where a number is carried
forward from an earlier measurement, the section and the date it was taken are
given at the number.

---

## 0. The three faces, and which one this card built

| where | the defect | this card |
|---|---|---|
| **Layer 1** — `goodwe/master/goodwe-master-stage4-failsafe.yaml:690` | the ingest-age veto tests the **VALUE** of `sensor.goodwe_p1_sample_age`, not its arrival. A dead publisher freezes it at a healthy number and the veto can never fire | **not touched.** It is firmware, behind a flash. §5 says what it owes |
| **The add-on** — `app/hass.py:69-82` | returns a held value as a value. Nothing separates "read 40 %" from "still says 40 % because nothing updated it" | **built here** |
| **The evidence** — [[HW-01]] | SoC held 40 % for 6 h 25 m while the pack drained to its floor, every detector reading healthy | the case the policy is answerable to |

The two consumers the card names — SAFETY-30's per-unit sign check and
SAFETY-31's circulating-power sensor — both read `Inverter.batt` (register
`0x0518`) and **neither had a freshness gate of any kind**. Both already do the
right thing with a `None`: `watchdog.SignWatchdog.evaluate` **clears** its window
on a `None` measurement, and `circulation.circulating_w` returns `None` for a
roster with a missing term, which clears that window too. **Neither could ever
receive one.** The gate is the piece that was missing *between* the shipped read
and the shipped checks, which is why the change to each consumer is zero lines.

---

## 1. ⚠️ The sentence that had to be rewritten, and why saying so is the finding

The card says: *"A pack legitimately resting at 40 % and a dead sensor reading
40 % are the same number; **only arrival separates them**."*

**For a signal this add-on polls out of Home Assistant's state cache, arrival
does not separate them, and cannot.** `read_inputs()` runs about once a second
(`run_control()`'s `await asyncio.sleep(1)` bounds the loop body), and while the
entity exists Home Assistant answers `200` with a number **whether or not the
publisher behind it is alive**. So both members of the pair arrive, identically,
for ever. `test_freshness.py` part 1a builds an arrival-age gate and grades it:
the age since arrival is `0.0 s` at every instant of **both** runs. A threshold
on it is a threshold that can never fire — which is TEL-06's own defect rebuilt
one layer up.

The other half of the card's rule survives intact and is honoured absolutely:

> ⚠️ Home Assistant's `last_updated` does **not** move when a value is rewritten
> unchanged, so it cannot be the source of truth.

Neither does `last_changed`, and this project measured on the ENV-01 rig (70 s of
a frozen meter) and independently against the live house that `last_reported`
does not advance on a repeat on either serialiser either —
`p1.HomeWizardLocalSource`'s docstring records both. **`app/freshness.py` reads
no Home Assistant timestamp at all.** Every clock in the verdict is
`time.monotonic()` inside this process, stamped at the instant an arrival carried
a different number. That is what "arrival-stamped" can mean here, and it is
graded (part 1a asserts the module's body contains no `last_updated`).

**So the criterion was rewritten rather than approximated:** *a reading is stale
when it has not moved through a change it was obliged to follow.* The obligation,
not the age, is what separates the pair.

---

## 2. The verdict

```
STALE  ⟺  unchanged for ≥ 35.0 s
          AND |standing command now| ≥ 250 W
          AND |standing command now − standing command when the reading
               last changed| ≥ 250 W
```

Latched: **only an arrival carrying a different number clears it.**

`0x0518` is the inverter reporting **itself** — r = 0.998 with battery power
against r = 0.09 with the real meter (`goodwe/NOTES.md` §3.3) — and it tracks its
own command: command and actual agreeing within 4 W once settled (§5.10,
measured 2026-08-22), the register dithering ±1 W while holding (§5.11, same
day). A unit told to move 250 W and still answering the same integer watt is not
tracking.

### 2.1 Why a bare "unchanged for N seconds" threshold is not available

**Measured, not feared.** Replaying the committed 30-day capture of this house's
own 1 W-resolution power entity — `scenarios/p1-net-30d-2026-08/`, 485,841
samples straight out of Home Assistant's recorder, where a row exists only when
the state string **changed**, so the gap between two rows *is* the unchanged
duration every consumer saw:

| | |
|---|---|
| longest unchanged run over 30 days | **263.2 s** (held −899.0 W, 2026-08-11 17:04) |
| runs ≥ 35 s | 10 of 485,840 (0.0021 %) |
| runs ≥ 17 s | 386 of 485,840 (0.0794 %) |

A real power figure at 1 W resolution held **one value for four and a half
minutes with nothing whatever wrong**. So an unchanged threshold free of false
positives must be over 263 s — and 263 s is **3.5× too slow** to protect a
consumer that trips at 75 s. There is no admissible threshold. The conjunction
is not a refinement; without it the card has no implementable verdict.

⚠️ **That is the METER's register, not `0x0518`, and it is used as a surrogate
and named as one.** No 30-day capture of the inverter's own power exists — it is
not in the recorder export. The single thing this measurement is used for is the
statement above: that the legitimate unchanged duration of a power entity in this
house is *minutes*. It is not used to set the bound.

⚠️ **And every one of those long runs happened under an unmoving load** — the
worst is 263 s of a steady −899 W export, a house doing one thing. That is why
the conjunction keys on command travel: none of them arms it.

### 2.2 Why the magnitude term exists — a surviving mutation put it there

Deleting `abs(standing_w) < move_w` from `_grade()` left **every check in the
first draft green**, because in all of them a command that had *travelled*
250 W had also *ended up* above 250 W. The case that separates them is a site
being brought to **rest**: the write path is serialised, so a register can reach
its new value on the same read at which the *old* command is still standing —
`standing_at_change` then captures 1300 W, the site is commanded to 0 W, and the
travel term alone reads 1300 W of unfollowed command for as long as the site
rests. It would call a perfectly truthful +5 W reading dead. The magnitude term
is what says *a site at rest is not owed movement*, and part 4 now grades it.

**The hole that term leaves cannot mislead either consumer**, which is why it is
the right trade: a unit commanded under 250 W is one `watchdog.disagrees()` is
`False` for whatever the measurement says, and a frozen term beside a live unit
that is itself resting nets to **zero** circulating power rather than to a false
alarm. Both halves are asserted, not argued.

---

## 3. The bounds — one per signal, each with its derivation

⚠️ **One constant for both signals would be useless on SoC or trigger-happy on
power**, which is the third clause of the policy. `freshness.BOUNDS` carries them
as data with a `wired` column, and `test_freshness.py` part 7 walks the AST of
every shipped module to check that column tells the truth.

### 3.1 `batt` — `0x0518`, S16, 1 W, published every 10 s — **WIRED**

**Floor, 17.0 s** — the fastest a healthy register can be *obliged* to have
answered. Three terms, each read out of this repository:

| | | source |
|---|---|---|
| 6.0 s | the plant | `goodwe/NOTES.md` §5.9, measured 2026-08-22 with the poll temporarily at 1 s: 26 W at +1.43 s, 469 W (94 %) at +3.34 s, settled 507 W at +6.05 s |
| 10.0 s | the publisher | `firmware/goodwe-master.yaml:181`, `update_interval: 10s` on the `modbus_controller` carrying both `0x0518` and `0x050E` |
| 1.0 s | this add-on's read period | `main.run_control()`'s `await asyncio.sleep(1)` |

**Ceiling, 75.0 s** — the tighter of the two consumers, both read out of the
shipped `config.yaml`: `circulation_hold_s` **75** (line 512) and
`unit_sign_disagree_s` **85** (line 451). A gate slower than its consumer hands
over the frozen number and explains afterwards.

**Chosen: 35.0 s.** The admissible band `[2 × 17.0, 0.5 × 75.0] = [34.0, 37.5]`
contains four integers, and **the band is what is derived — 35 is a choice inside
it**, deliberately not 30 (that is `validate.FIRMWARE_INGEST_VETO_S`, and would
read as a borrowed constant nobody re-derived) and not 60 (round). Part 6
computes both ends **from `config.yaml`** and goes red if an operator default
moves: drop `circulation_hold_s` to 60 and this fails.

**`MOVE_W` = 250 W** is the **largest** admissible value, not a sensitivity
preference. The gate must arm everywhere a stale reading could mislead a
consumer; the earliest either consumer speaks is `unit_sign_disagree_w`, 250 W
(config.yaml:450), because below that `watchdog.disagrees()` is `False` whatever
the measurement says. Taking the ceiling of the admissible range minimises
spurious arming. It is pinned to `config.yaml` by part 6, not to a literal.

### 3.2 `soc` — `0x050E`, U16, 1 %, published every 10 s — **STATED, NOT WIRED**

SoC **cannot use the conjunction above.** A pack resting at its floor holds one
percent for hours with nothing wrong — the card's own example — and the standing
command says nothing about it, because 0 W is exactly what a rested pack is
given. The obliged movement for SoC is **energy, not command travel**: one
percent of pack A is ≈ **153.6 Wh** (15.36 kWh nominal, `goodwe/NOTES.md` §1.1b's
table — ⚠️ **NOMINAL and FROM DATASHEET**, not a measured usable capacity), so at
pack A's 5000 W ceiling one percent takes at least **110 s**, and at a realistic
1000 W about **553 s**.

So the bound is *"SoC unchanged while ∫|battery power| dt since its last change
exceeded K × 153.6 Wh"*, and **K cannot be chosen from anything written down
today**. Wiring it with a guessed K would be a gate that fires on a rested pack,
which is the hazard, not the fix. `Freshness` takes its obligation term from the
caller precisely so an energy integral can be handed in where command travel is
handed in for `batt` — TEL-08 needs no second mechanism.

---

## 4. What changes on a running install

| | before | after |
|---|---|---|
| healthy register, N=1 | value reaches consumers | **identical** — 60 reads of a dithering register under a reversing command, asserted in part 5 |
| healthy register, N≥2 | value reaches consumers | identical |
| **frozen register, N=1** | reads as a healthy measurement, for ever | **site stops**: `inputs_ok` False → `stale_input_s` hold → 0 W, and keeps commanding |
| **frozen register, N≥2** | per-unit sign check false-trips at 85 s and parks a healthy inverter; circulation sensor reports a loop that is not happening | both consumers get `None`, both windows **clear** |

⚠️ **The N=1 row is a behaviour change on the roster that is running in a house
today, and it is named rather than hidden.** It is also the point of the card:
HW-01 was a one-inverter site. The direction it fails in is the safe one — a
false verdict commands 0 W and keeps commanding (§11.1 rule 1), behind the
existing `stale_input_s` hold, and clears itself on the register's next move.

The counterfactual is run, not argued. `test_freshness.py` part 3 drives real
`cycle()` calls at N=2 with A's register frozen at −1200 W and B's live at
+900 W, the command travel produced by the shipped `compute()` and allocator:

```
standing on A: [0, 445, 890, 1335, 1335, ...]      (the shipped control law)
gated       : sign trip tick=None   circulating_w=[1800, 1800, 1800, None, None, ...]
counterfact : sign trip tick=11      circulating_w=[1800, 1800, 1800, 1800, 1800, ...]
```

---

## 5. What TEL-06 and TEL-08 still owe

**[[TEL-06]] — layer 1, Blocked, and nothing in this card can reach it.** The
ESPHome veto tests the *value* of `sensor.goodwe_p1_sample_age`. This policy
lives in the add-on, on the other side of a flash, and cannot help. What TEL-06
owes is the same mechanism **inside the firmware**: a `millis()` stamp taken when
the setpoint/age entity is *written*, and a veto on `millis() − last_write_ms`
rather than on the published number. It is narrowed to that one substitution —
the policy question ("arrival, not value") is answered here; the remaining work
is a firmware stamp and a flash, which is a supervised human step.

**[[TEL-08]] — stale SoC.** It owes exactly three things, and no mechanism:
1. a **measured** usable capacity for pack A (or a defensible bound on it) — the
   153.6 Wh per percent above is nominal and from the datasheet;
2. the **energy integral** since the reading last changed;
3. the constant **K** — how many percent-equivalents of throughput must pass
   before an unmoved SoC is a fault.

It should consume `freshness.Freshness` with `BOUNDS["soc"]` filled in, not
restate the policy. The row is already in the table with `wired=False` and the
reason, and part 7 goes red the day that column stops being true.

**⚠️ Neither of them, and not this card, closes HW-01's whole class.** See §6.

---

## 6. Known survivors, with their size

Graded in `test_freshness.py` part 9, so they are residuals rather than
surprises.

| # | kind | what survives | size |
|---|---|---|---|
| 1 | **false positive** | an inverter physically unable to follow — saturating, thermally derating, or a BMS refusing a charge — is declared stale while telling the truth | one spurious **site stop**, behind `stale_input_s`, self-clearing the moment the register moves. It cannot drive the battery anywhere |
| 2 | **miss** | a register frozen under a command that never travels 250 W is never detected, for 400 s or for ever | ⚠️ scoped for ONE consumer, NOT both, and the earlier claim here was wrong. TRUE for the per-unit sign check: no such check can speak about that unit (`unit_sign_disagree_w` = 250 W). **FALSE for circulation.** "Contributing at most 250 W" bounds the COMMAND; once the register is frozen its REPORTED value is unrelated to the command, which is exactly HW-01's shape - commanded ~0 W, register stuck on the last large number. Measured: a unit frozen at −1200 W beside a healthy +900 W sibling yields `circulating_w` = **1800 W against the 700 W floor, 2.6× over**, with no gate armed. Found in review; part 9's S2 check asserts only `not stale` and part 4 pairs the frozen unit with a RESTING sibling, so neither graded the sentence |
| 3 | **miss — the largest** | a dead publisher whose last values **alternate**, or a cache replaying two old samples, never starts the unchanged clock at all | **this gate detects a value that STOPPED; it cannot detect a value that is WRONG.** Nothing in this add-on can. TEL-06's arrival stamp inside the firmware is the only layer that could |

Recorded because it looks like a survivor and is not: a publisher failure that
freezes **both** registers is caught on both units independently, on each unit's
own command travel and each unit's own number.

---

## 7. Mutation record — 2026-09-06

`tools/mutation_run.sh`'s rule, honoured on every run: purge first (count printed,
`0` remaining), tree mounted `:ro`, `python3 -B`, fingerprint the tree, **and
fingerprint again after the revert**. Clean tree `app/freshness.py`
`sha256:f40fa3e8819014ce` / 20,065 B, `app/inverter.py` `7e760c6e8cdfa5b7` /
30,778 B, `app/main.py` `7d7ff4ba0697ea64` / 238,535 B. Each mutant graded by
`test_freshness.py` + `test_inverter.py`.

| # | mutation | file | Δ B | result |
|---|---|---|---|---|
| M0 | none (control) | freshness | +0 | **green** — the harness is not red on everything |
| M1 | `reading()` returns `self.last` unconditionally | freshness | −24 | red, 3 named checks |
| M2 | drop the command-travel term | freshness | −59 | red |
| M3 | drop the magnitude term | freshness | −54 | **SURVIVED**, then red — §2.2. This is the finding |
| M4 | latch never holds | freshness | +13 | red, 3 named checks |
| M5 | bound 90 s (slower than both consumers) | freshness | **+0** | red |
| M6 | bound 10 s (under the physical floor) | freshness | **+0** | red |
| M7 | `MOVE_W` 700 W | freshness | **+0** | red, on part 6's `config.yaml` pin |
| M8 | the wiring in `_read_unit` removed | main | −5 | red, 3 named checks |
| M9 | reset the unchanged clock on every arrival (value-stamped) | freshness | −43 | red |
| M10 | `standing_w()` drops `last_write` | inverter | −73 | red, and takes `test_inverter.py` with it |
| M11 | `standing_at_change` refreshed on every arrival | freshness | +121 | ⚠️ **DISCOUNTED — the mutant does not parse** |
| M11b | the same defect, written parseably | freshness | +105 | red |
| M12 | `BOUNDS["soc"].wired = True` — the table lies | freshness | −1 | red |
| M13 | the wrong signal submitted (`inv.soc` for `inv.batt`) | main | +4 | red, and `test_inverter.py` too |
| M14 | one `Freshness` shared by every unit | inverter | +29 | red |
| M15 | latch cleared by a failed read | freshness | +31 | **SURVIVED**, then red — see below |

⚠️ **M5, M6 and M7 are `+0 B`, which MUTATION.md names as the risky delta.** All
three are **reds**, which is the direction stale bytecode cannot fabricate, and
every run purged with the count printed and graded a `:ro` tree that physically
cannot hold a cache.

⚠️ **M11 IS NOT A RESULT AND IS NOT COUNTED.** Its edit dedents a statement into
the middle of an `if` body, so the module raises `IndentationError` at line 312
and both files go red without a single check being evaluated. Verified by
`ast.parse` rather than assumed. **M11b** is the same defect written so it
parses, and it is a real red.

### The two survivors, and what each one taught

**M3, the magnitude term** — see §2.2. Two terms of a conjunction that move
together in every fixture are one term as far as the checks are concerned.
Recorded as `MUTATION.md` **habit 17**, twelfth instance of "a check whose DATA
cannot reach the failure it names".

**M15, the latch cleared by a failed read** — found only because the sweep went
looking for what the checks would NOT see. No fixture had ever injected a read
failure *while latched*, and it matters: a stale verdict stops the site, the site
is then commanded 0 W, and one unreachable-Home-Assistant read would drop the
latch into a state where the conjunction is no longer armed — so the held
−1200 W would come back to the consumers on the very next successful read. Part 4
now grades exactly that and M15 is red.

### And one process defect worth more than the ledger

One mutation's container run overran a two-minute command budget and the wrapper
was killed **between the edit and the revert**, leaving `app/freshness.py`
mutated on disk. Nothing announced it; the next mutation's harness cheerfully
fingerprinted and graded the mutant *plus* a second mutation. It was caught by
comparing the tree fingerprint against the recorded clean one, restored, and
verified back to byte and `sha256` before anything else ran. Same defect as stale
bytecode, different cause. Recorded as `MUTATION.md` **habit 18**: *fingerprint
after the revert, not only before the run.*

### A third, in this file's own fixture

M2 originally reported "red" with **no named check behind it**. The mutant makes
the FRESH run stale, so `test_freshness.py`'s own diagnostic
`print(f"… {sorted(set(_fresh_read))}")` raised `TypeError` comparing `None` with
a float **before check one ran**. MUTATION.md's reporting rule is *"which suite
went red, and on which named check"*, and a print that can crash first destroys
exactly that. Sorted with `key=str` now; M2 reports its check.

### Re-verified at the committed head

The 16-row sweep above graded `test_freshness.py` as it stood when each mutation
ran; the two closures (M3's part-4 check, M15's failed-read check), the `key=str`
fix and the wall-clock hardening all landed afterwards. So six mutations were
re-run against **the exact tree that is committed** —
`test_freshness.py sha256:a62f3e1f1ac856cf`, 44,913 B:

| # | result at head |
|---|---|
| M0 control | **green** |
| M2 drop the command-travel term | red, on part 1's "FRESH AND UNCHANGED is not stale" |
| M3 drop the magnitude term | red, on part 4's magnitude check |
| M8 wiring removed | red, on three named checks in parts 2 and 3 |
| M11b `standing_at_change` drifts | red, on three named checks in part 1 |
| M15 latch cleared by a failed read | red, on part 4's failed-read check |

The other ten are unaffected by those edits: each is red on a check in parts 1,
2, 4, 6, 7 or 9 that none of them touches, and a mutation red on one check
cannot be made green by adding another.

### The wall clock, which part 3 cannot avoid and therefore measures

The freshness verdict runs on an injected monotonic clock and is deterministic.
The sign watchdog inside `cycle()` cannot be injected, so part 3 runs against the
real one — which is CI-06's failure mode exactly (`test_peakguard.py` answered
two checks with the wall clock, flaked at ~20 %, and cost a wrong merge
diagnosis). So the margin is measured and asserted rather than assumed:

    gate closed after 0.61 s of WALL clock, against the 2 s watchdog window (3.3x margin)

If a loaded machine ever narrows that, the check fails **naming the number**,
which is the difference between "the box was slow" and "the code is broken".