Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Claude
|
8fa4febfef | ||
 admin
|
8f82dd4e06 | ||
|
glenn schrooyenandClaude Opus 5
|
e1b9254626 | ||
|
admin
|
478ba93710 |
@@ -27,6 +27,43 @@ if it has, it needs 0.10.0. Whoever deploys decides.
|
||||
| _this branch_ | TARIFF-17 - a price component that varies by hour has somewhere to live, so a Walloon day/night network tariff can change which hour is cheapest |
|
||||
| _this branch_ | TARIFF-18 - `price_taxes_eur_kwh` stops shipping at half the real Flemish figure **⚠️ CHANGED DEFAULT** |
|
||||
| _this branch_ | TARIFF-16 - the injection leg stops being one number: an injection formula with its own coefficients, its own VAT and no floor under zero |
|
||||
| _this branch_ | SAFETY-45 - a price-driven charge is SIZED by the capacity-tariff guard instead of being switched on and off by it **⚠️ CONTROL STABILITY** |
|
||||
| _this branch_ | SAFETY-10 - shadow mode: the whole decision path runs and nothing reaches the inverter **⚠️ NEW OPTION, DEFAULT-ON FOR A NEW INSTALL** |
|
||||
|
||||
### SAFETY-10 — shadow mode, and what its default does to YOUR install
|
||||
|
||||
A new option, `shadow_mode`, with three values and a shipped default of
|
||||
`auto`. In shadow mode the add-on runs its entire decision path — strategies,
|
||||
arbiter, clamps, guards — and **sends nothing to the inverter**: every inverter
|
||||
is held at **0 W**, refreshed on the ordinary heartbeat by the ordinary single
|
||||
writer, and the status page says plainly that the battery is not being
|
||||
controlled. What it *would* have commanded, and why, is on the status page and
|
||||
in the action log.
|
||||
|
||||
⚠️ **WHAT HAPPENS TO AN EXISTING INSTALL: NOTHING.** `auto` resolves to shadow
|
||||
mode only while control is **stopped**. An install that is controlling —
|
||||
`auto_start: true`, or *Start / stop control* pressed — is started, so `auto`
|
||||
resolves to ordinary control and not one watt changes. An install that is
|
||||
**stopped** keeps its actuator at 0 W exactly as it did before, from the same
|
||||
writer on the same heartbeat; what changes for it is what the status page and
|
||||
the action log **say**, and that the decision path now runs and is recorded.
|
||||
|
||||
⚠️ **AND THAT IS WHY IT IS NOT A BOOLEAN.** The card is titled "default-on".
|
||||
Taken literally — `shadow_mode: true` in `config.yaml` — it would be the worst
|
||||
change in this repository's history: the Supervisor composes an add-on's
|
||||
options as *its defaults, overlaid with the stored user options*, so a new key
|
||||
with a new default reaches **every existing install** on the next update,
|
||||
including the one regulating a real battery at the reference site. It would
|
||||
have silently stopped it, and the only symptom would have been a battery that
|
||||
stopped doing anything. There is no mechanism in the add-on options system that
|
||||
lets one key default differently for a new install and an existing one, so
|
||||
"default-on for new" is expressed as a value the add-on **resolves** rather
|
||||
than a constant the Supervisor merges.
|
||||
|
||||
A **new** install ships `auto_start: false`, so it comes up in shadow mode and
|
||||
observes a day of decisions before it is allowed to command anything. That is
|
||||
the default-on the card asked for, delivered where it is safe and withheld
|
||||
where it is not.
|
||||
|
||||
⚠️ **A CONFIG THAT STARTS ON THE CURRENT VERSION CAN BE REFUSED ON THE NEXT
|
||||
ONE.** TARIFF-07 withdraws `engie_dynamic`, `totalenergies_dynamic` and
|
||||
@@ -62,6 +99,80 @@ separate card. *(Annotated 2026-09-13: that card is **TARIFF-15**, below, and it
|
||||
shipped on this branch as `custom_formula`. It is still not an alias — the
|
||||
operator types their own coefficients; nothing is invented on their behalf.)*
|
||||
|
||||
### SAFETY-45 - the trade is sized by the capacity guard, not switched by it
|
||||
|
||||
**A price-driven charge now asks the peak guard HOW HARD it may pull, instead of
|
||||
only whether it may pull at all.** On any site where `load + max_w` reaches
|
||||
`peak_cap_w` - at the shipped `peak_cap_w: 3500` and `max_w: 2000`, any house
|
||||
drawing over 1500 W in the cheapest quarter - arbitrage and the capacity-tariff
|
||||
guard were driving each other in a sustained limit cycle. Measured on TEST-23
|
||||
stage 3's closed rig at `peak_cap_w: 1500` against a 1200 W house: **28 charge
|
||||
onsets in one hour, mean period 131 s, the grid swinging −456 to +3200 W**, and
|
||||
every billed quarter in the three affected configurations finishing **over** the
|
||||
cap it was oscillating about. §10.2: *"an EMS that oscillates is worse than no
|
||||
EMS, both for hardware wear and - per §9.1 - for the peak it is trying to
|
||||
avoid."*
|
||||
|
||||
**What was happening.** The guard computes `wanted = batt_w + excess` - the
|
||||
battery discharge that would land the quarter exactly on the ceiling - and files
|
||||
a claim only while that number is positive. While a trade charges at `max_w`
|
||||
the number is negative for the first minute or so of every cycle, so the guard
|
||||
files **nothing** and the trade is not constrained at all. `wanted` then crosses
|
||||
zero, the guard engages on a floor of a few watts, and that flips
|
||||
`arbitrage.guard_state()` - which cancels **the whole trade**. The
|
||||
grid-following loop takes the actuator, drives the meter to zero and past it,
|
||||
the projection collapses, the guard releases, and the trade comes back at
|
||||
`max_w`. 115 s later, again.
|
||||
|
||||
**The fix, and it is a shape this add-on already had.**
|
||||
`control.maintenance_charge_floor()` has always capped a MAINTENANCE charge at
|
||||
"the headroom left under the site's cap", because *"a maintenance charge is the
|
||||
only thing this system does that is big enough and long enough to set that
|
||||
peak"*. ⚠️ That stopped being true when OPT-04 landed: a trade commands `max_w`
|
||||
for a whole tariff interval, deliberately, against the meter.
|
||||
`peakguard.charge_headroom_w()` publishes the same quantity off the **measured**
|
||||
guard rather than off the optional `peak_forecast_entity`, and
|
||||
`arbitrage.decide()` sizes the buy leg to it.
|
||||
|
||||
**No new arithmetic and no new constant.** The number is `wanted_w` read in the
|
||||
other direction: a negative `wanted` is not "nothing to say", it is a permitted
|
||||
charge of `−wanted`. `peakguard.decide()` is **unchanged** - byte-identical to
|
||||
`release/1.0`, `sha256 = 200090d0835a3a55` - so 2026-08-20's anti-bang-bang rung
|
||||
is exactly where it was, and `tools/replay_ac3.py` reproduces the same 190/190
|
||||
guarded quarters, 110 engaged cycles and 878 Wh on this branch as on the tip.
|
||||
|
||||
**After, on the same rig, same command:**
|
||||
|
||||
| `peak_cap_w` / house | onsets per hour | grid swing | energy bought | billed quarters |
|
||||
|---|---|---|---|---|
|
||||
| 1500 / 1200 W | 28 → **1** | 3656 → **282 W** | 180 → **285 Wh** | 1490/1497/**1509** → **1500/1500/1500** |
|
||||
| 3500 / 1800 W | 8 → **1** | 3673 → 1688 W | 1653 → 1616 Wh | **3511/3536/3559** → **3500/3500/3500** |
|
||||
| 3500 / 3000 W | 32 → **1** | 3798 → **475 W** | 483 → 475 Wh | **3519/3542/3557** → **3500/3500/3500** |
|
||||
| 5000 / 1200 W | 1 → 1 | *identical* | *identical* | *identical* |
|
||||
|
||||
One onset means the trade starts once and runs for the whole window - the
|
||||
battery is now trading 100 % of the cheap hour where it traded 43 %, 92 % and
|
||||
54 %. **Every billed quarter now lands on the cap and none over it.** At the
|
||||
aggressive cap the site buys 58 % MORE energy, because a continuous 300 W trade
|
||||
beats a 2000 W trade that is cancelled for well over half the hour; at the two
|
||||
shipped-default rows it buys about 2 % less and the worst quarter drops from
|
||||
59 W over the cap to zero. The last row is the negative control - `load + max_w`
|
||||
never reaches the cap there, and the two runs are bit-identical. **This costs
|
||||
nothing on the installs it is not about.**
|
||||
|
||||
⚠️ **NOT A CONFIG CHANGE.** No option is added, removed or re-defaulted, and
|
||||
arbitrage remains off in the shipped configuration. A site that has not armed
|
||||
`arbitrage_enabled` is unaffected in every respect.
|
||||
|
||||
⚠️ **WHAT IS NOT FIXED, AND IT IS NAMED RATHER THAN IMPLIED.** TEST-23 finding 1
|
||||
- the export overshoot at the END of any trade, 356-938 W, about 0.37 × `max_w`
|
||||
- is untouched and is a different card. A house whose load ALONE exceeds
|
||||
`peak_cap_w` still has the guard engage and the trade refused outright, which is
|
||||
correct, and the grid-following loop then drives to grid = 0 rather than to the
|
||||
ceiling. See `DECISIONS/SAFETY-45-sizing-the-trade.md` §5, and §2 there for the
|
||||
negative-`lo` design that was rejected because it creates a new `lo > hi`
|
||||
contradiction against the maintenance charge shaping.
|
||||
|
||||
### TARIFF-16 - the injection leg stops being one number
|
||||
|
||||
**`price_export_formula`: what a site is PAID for export, as `factor × index +
|
||||
|
||||
@@ -0,0 +1,321 @@
|
||||
# SAFETY-10 — shadow mode, and why "default-on" is not `true`
|
||||
|
||||
**Status:** decided and implemented on branch `SAFETY-10`.
|
||||
**Card:** SAFETY-10 — *"Shadow mode (default-on, log-only decisions)"*.
|
||||
**Nothing here reached the inverter.** No deployment, no `ha addons update`, no
|
||||
contact with 192.168.2.158 or 192.168.2.221. Everything below was measured in
|
||||
the CI image and on TEST-23 stage 3's closed-loop rig.
|
||||
|
||||
---
|
||||
|
||||
## 0. The four things a reader should take away
|
||||
|
||||
1. **"Default-on" is delivered as `auto`, not as `true`, and the difference is
|
||||
an install that is regulating a real battery today.** The Supervisor
|
||||
composes an add-on's options as *its defaults, overlaid with the stored user
|
||||
options*, so a new key with a new default reaches **every existing install**
|
||||
on the next update. A boolean `shadow_mode: true` would silently stop the
|
||||
reference site. §1.
|
||||
2. **Shadow mode WRITES. It writes 0 W, on the ordinary heartbeat, through the
|
||||
ordinary single writer.** "Commands nothing" implemented as "stops writing"
|
||||
would leave the inverter latched on whatever was standing — it has no meter
|
||||
timeout — and would put the ESP32 into a tripped stale-input watchdog for
|
||||
the whole run. §2.
|
||||
3. **The sign watchdogs are inert, and that was the decision that had to be got
|
||||
right.** Fed the shadow decision they would trip within `sign_disagree_s`
|
||||
and **latch a trip that survives into live operation and a restart**. §4.
|
||||
4. **The loop leg's shadow decision is one slew step, not a trajectory, and
|
||||
that is a real limitation of this feature.** §5.
|
||||
|
||||
---
|
||||
|
||||
## 1. The default
|
||||
|
||||
### The literal reading, and what it costs
|
||||
|
||||
`config.yaml`'s `options:` block **is** the default. There is exactly one of it,
|
||||
and HA's Supervisor resolves an add-on's effective options as
|
||||
|
||||
```
|
||||
{**config.yaml options, **the stored user options}
|
||||
```
|
||||
|
||||
A key that has never been stored therefore takes the file's value — on a fresh
|
||||
install and on an install that has been running for months, identically. There
|
||||
is **no mechanism in the add-on options system** by which one key can default
|
||||
differently for the two. So the card's title, taken at face value, is:
|
||||
|
||||
> the next `ha addons update` stops the battery at the reference site, and the
|
||||
> only symptom is a battery that has stopped doing anything.
|
||||
|
||||
That is strictly worse than every defect shadow mode exists to catch. It is
|
||||
refused.
|
||||
|
||||
### What was shipped instead
|
||||
|
||||
`shadow_mode` is a three-valued `list(auto|on|off)` defaulting to `"auto"`:
|
||||
|
||||
| value | resolves to |
|
||||
|---|---|
|
||||
| `off` | live |
|
||||
| `on` | shadow, always |
|
||||
| `auto` | shadow **while control is stopped**; live once it is started |
|
||||
|
||||
`auto` reads `Controller.auto` — the persisted start/stop state, which a fresh
|
||||
install takes from `auto_start` and which the *Start / stop control* button
|
||||
moves. No new persisted state, no migration, no guess:
|
||||
|
||||
* a **fresh** install ships `auto_start: false`, has no stored `auto` key, and
|
||||
therefore comes up **in shadow mode**. It observes a day of decisions before
|
||||
it is ever allowed to command anything. That is the card's intent, delivered
|
||||
where it is safe;
|
||||
* an install that is **controlling** is started, so `auto` resolves to live and
|
||||
**not one watt changes**;
|
||||
* an install that is **stopped** keeps its actuator at 0 W exactly as before —
|
||||
the same number, from the same writer, on the same heartbeat. What changes is
|
||||
what the status page and the action log **say**, and that the decision path
|
||||
now runs and is recorded.
|
||||
|
||||
⚠️ **Under `auto`, pressing Start leaves shadow mode.** That is the point of
|
||||
`auto`: the button means "control the battery". An operator who wants the
|
||||
decisions recorded *while the loop runs* — the configuration this card exists
|
||||
to make possible — sets `on` explicitly, and cannot reach it by accident.
|
||||
|
||||
⚠️ **An unrecognised value resolves to SHADOW, and is REFUSED at startup.**
|
||||
`shadow.mode()` fails toward inaction; `validate.py` rule 11 refuses the value
|
||||
by name so the reinterpretation is never silent. A typo is not a decision, and
|
||||
an install silently left in shadow mode commands nothing indefinitely while its
|
||||
status page calmly explains that this is intentional.
|
||||
|
||||
---
|
||||
|
||||
## 2. "Commands nothing" is a number, not a silence
|
||||
|
||||
The inverter holds its last command **forever** — `HANDOVER.md` §6 says so, and
|
||||
`firmware/goodwe-master.yaml`'s header records what it cost when a controller
|
||||
stopped refreshing: *"Illusmart went silent mid-command and the inverter held
|
||||
+5000 W for 113 s"*. `firmware/goodwe-master.yaml` states the contract that follows — *"HA
|
||||
must now REWRITE the setpoint every ~10 s even when the value has not
|
||||
changed"* — because without a refresh, **"stale" and "steady" are the same
|
||||
thing on the wire**.
|
||||
|
||||
So shadow mode holds the actuator at `shadow.WIRE_W` = **0.0 W**, refreshed on
|
||||
the ordinary heartbeat. Two consequences were weighed and are recorded:
|
||||
|
||||
* **it is not silence.** A shadow mode that stopped writing would leave the
|
||||
standing command up until the ESP32's 30 s watchdog noticed — and at a site
|
||||
with no such board, forever;
|
||||
* **it does not use an alarm as a mode.** Letting that watchdog trip for the
|
||||
duration of a shadow run teaches the operator that `wd_tripped` is normal,
|
||||
which is exactly the training that makes it useless when the add-on has
|
||||
actually died.
|
||||
|
||||
### It is not a second writer
|
||||
|
||||
SAFETY-28's rule is one actuator, one writer. Shadow mode files **no claim**,
|
||||
owns **no transport**, and calls nothing in `hass.py`. It is a **substitution**
|
||||
inside `Controller._write_unit()` — the single choke point every write in this
|
||||
add-on already reaches, including the heartbeat, the stop button, `shutdown()`
|
||||
and `maint_abort()` — in exactly the form of the three substitutions above it
|
||||
(non-finite → 0 W, unauthorised → 0 W, clamped → the rating).
|
||||
|
||||
It is the **last** of them. Below SAFETY-28's gate and below SAFETY-03's clamp,
|
||||
so both still grade the number the decision path actually produced, and a
|
||||
shadow run can report *"it would have hit the rating here"*.
|
||||
|
||||
---
|
||||
|
||||
## 3. What the run records
|
||||
|
||||
| surface | what it carries |
|
||||
|---|---|
|
||||
| status banner | `SHADOW MODE - the battery is NOT being controlled...`, **first in the cascade**, amber — red, with the latch named, if one is standing |
|
||||
| status row `Shadow mode` | which rung decided, the watts it **would have commanded**, where the inverter actually is, and `Resolution.explain()` |
|
||||
| status row `Commanded` | `0 W` — the truth, which the row above reconciles with the `Why` row below it |
|
||||
| action log | one line when shadow mode comes on; one line per **change of decision** (winner or rounded watts), carrying the arbiter's own sentence |
|
||||
| MQTT | `status: shadow`, its own value, below `failsafe` |
|
||||
|
||||
The action log is **edge**-logged, not level-logged: the log holds 40 rows, and
|
||||
a line per cycle would flush the context of the run's own findings inside four
|
||||
minutes at the 15 s cycle floor.
|
||||
|
||||
---
|
||||
|
||||
## 4. The failsafes, one by one
|
||||
|
||||
| failsafe | in shadow mode | why |
|
||||
|---|---|---|
|
||||
| SAFETY-02/30 sign watchdogs | **INERT** | They grade `Inverter.standing_w()` — what this controller has standing on the wire — and shadow mode holds that at 0 W, so they cannot arm. ⚠️ Fed the shadow decision instead they would disagree with a meter that never saw it and **latch a trip that survives into live operation and a restart**: shadow mode would manufacture the failsafe it exists to help debug. ⚠️ **Two rungs hold it there** — `last_write` (the wire gate) and `inv.target` (the re-seed) — which is MUTATION.md's masking shape, so the mutation that reproduces the hazard defeats both as a pair (M6). Driven singly, dropping the re-seed does not reproduce it at all — measured |
|
||||
| SAFETY-03 clamp | **OBSERVES** | Runs on the decision, sets `clamp_last`, logs every engagement. Changes no command |
|
||||
| SAFETY-28 write gate | **OBSERVES** | Same placement, same reason: the question is who chose the number |
|
||||
| SAFETY-18 meter freeze | **OBSERVES**, unchanged | It takes no action live either; both halves of its conjunction are as true in shadow |
|
||||
| SAFETY-07/24/25 peak guard | **OBSERVES** | Level-triggered, unlatched, files its claim as usual — SAFETY-45's limit cycle is visible from a shadow run, which is the point |
|
||||
| SAFETY-31 circulation | **OBSERVES AND MAY LATCH** | Its evidence is *measured* power. Packs pushing against each other while all are told 0 W is a real fault |
|
||||
| SAFETY-42 delivery | **OBSERVES AND MAY LATCH** | Same, against a share that is 0 W |
|
||||
| operator stop | **SUPPRESSED AS A CLAIM, ENFORCED AT THE WIRE** | The one deliberate change. Its `P_SAFETY` 0 W claim out-ranks everything, so leaving it in makes the recorded decision `"stopped"` on every cycle and the run answers the wrong question. The actuator ends at the same number either way, and the wire substitution is **strictly stronger**: a claim can be out-ranked, and it cannot |
|
||||
| inputs missing, non-finite, allocator refusal, arbiter contradiction | **UNCHANGED** | All resolve to 0 W, which is what the wire gets anyway |
|
||||
|
||||
⚠️ **A latch that is already up stays up.** Nothing here clears one. The shadow
|
||||
banner **names** any standing latch and goes red for it, because a latch that is
|
||||
up while the controller is inert is up the moment it stops being inert.
|
||||
|
||||
⚠️ **Maintenance is not in that table because shadow mode does not touch it.**
|
||||
The state machines are ticked on every cycle whether control is started or not,
|
||||
so a stopped install already runs them against a battery that does not move.
|
||||
Shadow mode inherits that, unchanged and unimproved. Recorded here rather than
|
||||
quietly fixed under another card's name.
|
||||
|
||||
---
|
||||
|
||||
## 5. The limitation, stated rather than discovered later
|
||||
|
||||
`Controller._shadow_settle()` re-seeds the carried command (`self.target` and
|
||||
each `inv.target`) to `WIRE_W` at the **end** of every shadow cycle — after
|
||||
every in-cycle guard has read the decision. Three machines read that value as a
|
||||
statement about the **hardware**: the loop's `prev_w` and integrator,
|
||||
`standing_w()`, and SAFETY-42's share comparison. Re-seeded, they track reality,
|
||||
and **the exit is safe by construction** — the carried command already equals
|
||||
the standing one, so the first live cycle slews from 0 W like any other.
|
||||
|
||||
⚠️ **The cost is real.** The loop's `prev_w` is therefore 0 W on every shadow
|
||||
cycle, so the loop leg's recorded decision is **one slew step from the standing
|
||||
command** and stays there. A shadow run answers *"what would this controller
|
||||
command NOW, from where the plant really is"* — a true statement about the
|
||||
present — and **not** *"what trajectory would it have followed"*. The trajectory
|
||||
is a closed-loop property, it did not happen, and reporting it would be a
|
||||
simulation of a plant that does not exist; three cycles in, such a number
|
||||
describes nothing.
|
||||
|
||||
The strategies are unaffected: arbitrage, the peak guard and maintenance all
|
||||
file `SET` claims at a fixed power from level-triggered inputs. That is why the
|
||||
three defects this card was written for — SAFETY-45's 28 onsets an hour,
|
||||
TARIFF-14's wrong quarter-hour, SAFETY-46's ceiling churn — are all visible from
|
||||
a shadow run, and the loop's ramp is not. Graded, named, in
|
||||
`test_watchdog.py` part 10 as `RECORDED LIMITATION`.
|
||||
|
||||
---
|
||||
|
||||
## 6. How "nothing reaches the inverter" is graded
|
||||
|
||||
**Not on a flag.** A check that asserted `Controller.shadow` would pass on a
|
||||
build in which the flag is set and the substitution is deleted — which is
|
||||
exactly mutation **M1**.
|
||||
|
||||
`test_clamp.py` part 8 drives the **shipped** `Controller.cycle()` and the
|
||||
shipped heartbeat against a recording Home Assistant stub, and asserts on what
|
||||
reached `set_number()`:
|
||||
|
||||
* **the precondition first** — the same stimulus with `shadow_mode: off` puts
|
||||
30 non-zero writes on the wire, the largest 5000 W. MUTATION.md habit 4: a
|
||||
check whose data cannot reach the failure it names is decoration;
|
||||
* then `set(writes) == {0.0}`, **and** that there were 26 of them — a check
|
||||
that only said "no non-zero write" would pass on the silent build too;
|
||||
* entry and exit are measured on `inv.last_write` — what the inverter is
|
||||
latched on, updated only on an **accepted** write — either side of the
|
||||
boundary, against the same run that never entered shadow mode.
|
||||
|
||||
The closed-loop half is `/home/homelab/s10-mut/shadowloop.py` on TEST-23 stage
|
||||
3's rig: the same hour, twice, against `plantsim.Plant` through the firmware's
|
||||
own frame encoder.
|
||||
|
||||
| | live | shadow |
|
||||
|---|---|---|
|
||||
| `plant_cmd_w` | −2000 W throughout | **0 W throughout** |
|
||||
| `batt_w` | −2000 .. −40.6 W | **0.0 W, exactly** |
|
||||
| SoC | 50.000 → **62.331 %** | 50.0 → **50.0 %** |
|
||||
| grid | 390.6 .. 2350 W | **350 W = the house, exactly** |
|
||||
| `ARBITRAGE_CHARGE` samples | 3600 | **3600** |
|
||||
| first charge instant | 2026-01-15T00:00:00+00:00 | **identical** |
|
||||
| `arb_power_w` | −2000 W | **identical** |
|
||||
| `arb_reason` | the strategy's own sentence | **identical, verbatim** |
|
||||
| arbiter winner | `arbitrage` | **identical** |
|
||||
|
||||
The decision happened, at the same instant, for the same reason, at the same
|
||||
signed power — and the battery did not move.
|
||||
|
||||
⚠️ **Three lines of that harness are a TRANSCRIPTION and are marked as one.**
|
||||
`priceloop.Rig` has no `_write_unit()`, no clamp and no failsafe machine
|
||||
(divergence 2 of its README), so the substitution's **placement** is
|
||||
transcribed there. The shipped placement is graded by `test_clamp.py` part 8,
|
||||
which drives the real `Controller`. ⚠️ **And the rig's transcribed cycle
|
||||
predates SAFETY-45**: `arbitrage.decide()` gained a required
|
||||
`charge_headroom_w` after `478ba93`, and the harness supplies it from the
|
||||
**shipped** `peakguard.charge_headroom_w()` reading the **shipped** peak
|
||||
decision rather than from a constant, so SAFETY-45 stays in the run.
|
||||
|
||||
---
|
||||
|
||||
## 7. The mutation battery — 22 mutations, no survivors
|
||||
|
||||
Harness: `/home/homelab/s10-mut/run.py`, backups beside it. Each run restores
|
||||
from backup, purges `__pycache__` **on the host**, and grades through the CI
|
||||
image with the tree bind-mounted `:ro`, so the interpreter cannot write a cache
|
||||
into the tree under test (TEST-15). The full table is in the branch report;
|
||||
one per new behaviour, including **M1** (the substitution deleted — a write
|
||||
escapes), **M2** (it returns instead of substituting — the inverter is left
|
||||
latched), **M3** (it moves above SAFETY-28 and SAFETY-03 — the observers go
|
||||
blind), **M8** (`auto` resolves to shadow unconditionally — the literal
|
||||
default-on that stops the live install), **M12** (the stop claim is filed in
|
||||
shadow — every recorded decision reads `stopped`), **M21** (the substitution
|
||||
and the re-seed together) and **M22** (the re-seed moved one line earlier —
|
||||
SAFETY-18 grades a 0 W no decision produced and goes permanently blind).
|
||||
|
||||
⚠️ **Two findings from driving it, both of the kind MUTATION.md says to expect.**
|
||||
|
||||
* **M2 first came back a SURVIVOR and was not one.** The "stop writing
|
||||
altogether" build left `inv.last_write` as `None`, the check did `float()` on
|
||||
it, and the section died with a `TypeError` — grading none of the checks
|
||||
after it and reporting **zero reds**, which reads exactly like a survivor.
|
||||
That is FCST-06's shape. The fixture now hands `None` back and names it as
|
||||
its own check; M2 is red on three.
|
||||
* **M6 had to become a PAIR, and only the battery said so.** `standing_w()`
|
||||
prefers `last_write` — the 0.0 W the wire gate accepted — and falls back to
|
||||
`inv.target`, which the re-seed also holds at 0.0. Either rung alone keeps
|
||||
the detector inert, so dropping the re-seed **singly** came back red on the
|
||||
limitation check and on **nothing about the latch**: the hazard it names was
|
||||
not reproduced. TEST-16's rule with a new name on it.
|
||||
* **M7/M8/M9/M19 had to MOVE SUITES.** They defeat `shadow.engaged()`, and a
|
||||
defeated default stops `test_clamp.py` part 3's wired run reaching the wire
|
||||
at all — aborting the file with an `IndexError` before part 8 is graded. The
|
||||
red count there was a lower bound naming the saturation freeze. The mode
|
||||
table now lives in `test_validate.py`, which drives no Controller.
|
||||
* **`shadow_would_w = float(self.target)` is an EQUIVALENT mutation and was
|
||||
measured as one.** `_shadow_settle()` runs before the re-seed, so at that
|
||||
line `self.target` **is** `resolution.target_w`. It is recorded as equivalent
|
||||
rather than reported as a survivor, and the non-equivalent form of the same
|
||||
defect — the record becoming the **wire** — is driven instead.
|
||||
|
||||
### The table
|
||||
|
||||
Each row: the mutation, the file, the byte delta, the suite it was graded in,
|
||||
and how many **named** checks went red. `⚠️` marks a row whose run did not
|
||||
reach the end of its file, so its count is a **lower bound** (MUTATION.md).
|
||||
|
||||
| # | mutation | file | Δ | suite | reds |
|
||||
|---|---|---|---|---|---|
|
||||
| M1 | **a write escapes** — the substitution deleted | `main.py` | −6 B | clamp | 5 |
|
||||
| M2 | **silence instead of 0 W** — it returns rather than substituting | `main.py` | −15 B | clamp | 3 |
|
||||
| M3 | **the observers go blind** — it moves above SAFETY-28 and SAFETY-03 | `main.py` | +58 B | clamp | 1 |
|
||||
| M4 | the site re-seed dropped — the exit resumes from a fiction | `main.py` | −36 B | clamp | 3 |
|
||||
| M5 | the per-unit re-seed dropped | `main.py` | −22 B | clamp | 1 |
|
||||
| M6 | **PAIRED**: `standing_w()` reads the target **and** the re-seed dropped — the sign latch that survives into live operation | `inverter.py` + `main.py` | −170 B | watchdog | 3 |
|
||||
| M7 | `auto` inverted — shadow while started, live while stopped | `shadow.py` | +2 B | validate | 4 |
|
||||
| M8 | **default-on for everyone** — `auto` always shadow; the literal reading that stops the live install | `shadow.py` | −15 B | validate | 2 |
|
||||
| M9 | an unreadable value resolves to LIVE instead of shadow | `shadow.py` | +1 B | validate | 1 |
|
||||
| M10 | `validate.py` stops refusing an unknown value | `shadow.py` | −9 B | validate | 9 |
|
||||
| M11 | the loop leg gated on `auto` alone again — the decision path stops running | `main.py` | −17 B | clamp | 1 |
|
||||
| M12 | the stop claim filed in shadow — every decision reads `stopped` | `main.py` | −20 B | clamp | 1 |
|
||||
| M13 | the banner goes green while nothing is commanded | `shadow.py` | −2 B | clamp | 1 |
|
||||
| M14 | the banner loses the standing latch | `shadow.py` | −2 B | clamp | 1 |
|
||||
| M15 | the row renders the standing command instead of the decision | `shadow.py` | −8 B | clamp | 1 |
|
||||
| M16 ⚠️ | the row disappears when live | `main.py` | +43 B | clamp | 1 |
|
||||
| M17 | the record becomes the wire | `main.py` | −6 B | clamp | 7 |
|
||||
| M18 | level-logged — the 40-row action log floods | `main.py` | −23 B | clamp | 1 |
|
||||
| M19 | the two rungs render identically (masking) | `shadow.py` | +22 B | validate | 1 |
|
||||
| M20 | the shipped default moves to `off` in `config.yaml` alone | `config.yaml` | −1 B | defaults_pin | 1 |
|
||||
| M21 | **PAIRED**: the substitution **and** the re-seed deleted together | `main.py` | −103 B | clamp | 10 |
|
||||
| M22 | the re-seed moved one line earlier — SAFETY-18 grades a 0 W no decision produced and goes permanently blind | `main.py` | +40 B | clamp | 1 |
|
||||
|
||||
**Survivors: none.** ⚠️ **M17's `+0 B`-adjacent sibling** —
|
||||
`shadow_would_w = float(self.target)` — is recorded in §7 as **equivalent**
|
||||
rather than counted here.
|
||||
@@ -0,0 +1,221 @@
|
||||
# SAFETY-45 — the trade is SIZED by the capacity guard, not switched by it
|
||||
|
||||
**Status: closed.** `peakguard.charge_headroom_w()` publishes the watts the open
|
||||
billed quarter can still afford; `arbitrage.decide()` takes it as a required
|
||||
keyword-only argument and sizes the BUY leg to it; `main.py` passes the measured
|
||||
guard's own number at its one call site. `peakguard.decide()` is **not changed** —
|
||||
byte-identical to `release/1.0` at `478ba93`, `sha256(decide) = 200090d0835a3a55`,
|
||||
7252 B on both trees.
|
||||
|
||||
⚠️ **THE HOUSE LOAD IN EVERY FIGURE BELOW IS SYNTHETIC.** TEST-23 stage 3's
|
||||
`priceloop.py` drives a flat modelled house against a modelled pack
|
||||
(`plantsim.Plant`, 800 W/s ramp into a 10 s lag, 15 360 Wh). The PRICES are real,
|
||||
the decision code is the shipped code, the billed-quarter accumulator is
|
||||
`app/p1.py`'s own — the load is not. Nothing here is a measurement of the live
|
||||
site at 192.168.2.158, which this work did not touch.
|
||||
|
||||
## 0. The defect, measured
|
||||
|
||||
TEST-23 stage 3 found a sustained limit cycle with arbitrage armed and a charge
|
||||
decision active. Re-measured here on the same rig against the same checkout,
|
||||
metrics recomputed rather than copied — a **charge onset** is a cycle at which
|
||||
`arbitrage.decide()` transitions into `ARBITRAGE_CHARGE`, which is the edge the
|
||||
rig already logs:
|
||||
|
||||
| `peak_cap_w` | house | onsets/h | mean period | grid swing | billed quarters (W) |
|
||||
|---|---|---|---|---|---|
|
||||
| 1500 | 1200 W | **28** | 131.1 s | **−455.5 … +3200.0 W** | 1490.1 / 1496.5 / **1508.8** |
|
||||
| 3500 *(shipped)* | 1800 W | 8 | 509.3 s | +127.5 … +3800.0 W | **3511.3 / 3536.0 / 3559.1** |
|
||||
| 3500 *(shipped)* | 3000 W | 32 | 114.8 s | +1202.0 … +5000.0 W | **3518.9 / 3542.2 / 3556.7** |
|
||||
| 5000 | 1200 W | 1 | — | +1240.6 … +3200.0 W | 3169.5 / 3200.0 / 3200.0 |
|
||||
|
||||
The last row is the **negative control**: `load + max_w = 3200 W` never reaches
|
||||
the cap, so there is no cycle to remove. The bite rule is `load + max_w >
|
||||
peak_cap_w`, which at the shipped `peak_cap_w: 3500` / `max_w: 2000` is any house
|
||||
drawing over 1500 W in the cheapest quarter.
|
||||
|
||||
§10.1's ordering did win on the money — the guard kept the quarters within tens
|
||||
of watts of the cap — but **every billed quarter in the three biting rows
|
||||
finished OVER it**, which is the thing §9.1 bills. §10.2: *"an EMS that
|
||||
oscillates is worse than no EMS, both for hardware wear and — per §9.1 — for the
|
||||
peak it is trying to avoid."*
|
||||
|
||||
## 1. ⚠️ The mechanism is NOT mainly the quarter boundary, and the card says it is
|
||||
|
||||
The card, and `.cache/s45.md` before it, describe the loop as *"at each quarter
|
||||
boundary the projection resets to 0, the guard disengages, and arbitrage re-arms
|
||||
at full power."* **That is not what the 28 onsets are.** Their timestamps, off
|
||||
the run above:
|
||||
|
||||
1, 231, 351, 471, 581, 696, 806, 896, 1136, 1256, 1371, 1486, 1596,
|
||||
1711, 1811, 2061, 2176, 2296, 2411, 2521, 2626, 2716, 2971, 3091,
|
||||
3206, 3321, 3431, 3541 (s, quarter boundaries at 900/1800/2700)
|
||||
|
||||
**23 of the 27 gaps are 90–120 s, mean 111.5 s, entirely inside one quarter.**
|
||||
The four long gaps — 230, 240, 250, 255 s — are precisely the four that SPAN a
|
||||
boundary, so the boundary **lengthens** the interval rather than causing an
|
||||
onset. Only three onsets land within 15 s of a boundary and one of those is
|
||||
`t = 1`, the start of the run.
|
||||
|
||||
The real cycle, read off the recorded fields at t = 1000…1180 s:
|
||||
|
||||
1. the trade charges at `−2000 W`; the meter sits at 3200 W against a 1500 W
|
||||
ceiling; `wanted = batt_w + excess` is **negative** (−132 → −8 W), so
|
||||
`decide()` files **nothing** and arbitrage is not constrained at all;
|
||||
2. `wanted` drifts up as the quarter's own history worsens and the `900 /
|
||||
remaining` gain grows, and crosses zero at t = 1055 with **`floor_w = 5.3 W`**;
|
||||
3. that 5 W floor flips `arbitrage.guard_state()` to `True`, which refuses the
|
||||
**whole trade** — so the setpoint goes from −2000 W to +5 W and the
|
||||
grid-following loop, which targets grid = 0 and not grid = ceiling, takes the
|
||||
actuator and discharges to **+1870 W**, exporting 420 W;
|
||||
4. the projection collapses, `wanted` goes negative, the guard releases, and
|
||||
arbitrage re-arms at **`max_w`**. 115 s later, again.
|
||||
|
||||
So the defect is **a binary interlock keyed on a continuous quantity**, and the
|
||||
quarter boundary is one of the ways it is crossed rather than the cause. The
|
||||
card's other claim — *"projection 3092 W against a 1509 W ceiling, `engaged=False`,
|
||||
for 170 consecutive seconds"* — reproduces, but it is the **first** such window
|
||||
(`first_engaged_t_s = 151.0`); the steady-state silent window is ~40–65 s.
|
||||
|
||||
None of this changes what the fix has to do. It is recorded because a card that
|
||||
says "the boundary is the trigger" invites a fix in the boundary handling, and
|
||||
such a fix would have removed four of twenty-eight onsets.
|
||||
|
||||
## 2. What was rejected, and why
|
||||
|
||||
### 2a. Reverting `decide()`'s `wanted <= 0.0` rung — rejected, and it is a trap
|
||||
That rung is 2026-08-20's anti-bang-bang. Its own comment records the cost of not
|
||||
having it: 17 engage/release cycles in 900 s and a quarter finishing 49 W over
|
||||
the limit it had spent a quarter of an hour holding. It is untouched, pinned on
|
||||
the AST in `test_peakguard.py` 13g, and `tools/replay_ac3.py` reproduces the same
|
||||
190/190, 110 engaged cycles, 5 blind, 878 Wh on this branch as on `478ba93`.
|
||||
|
||||
### 2b. Filing the affordable charge as a NEGATIVE `lo` — rejected
|
||||
Arithmetically this is the prettiest answer: `lo = wanted` with no sign gate is
|
||||
continuous, is exactly the control law `decide()` already computes, and would
|
||||
have put the constraint on the arbiter where it binds every claimant rather than
|
||||
only arbitrage. It was rejected on two grounds, in this order:
|
||||
|
||||
1. ⚠️ **IT CREATES A NEW `lo > hi` CONTRADICTION CLASS AGAINST THE MAINTENANCE
|
||||
SHAPING.** `main.py`'s cheap-window maintenance charge files
|
||||
`Claim.limit("maintenance", P_MAINT_SHAPE, hi=-floor)` — a NEGATIVE `hi`.
|
||||
`arbiter.py` clause 2 applies every limit at or above the winner's priority
|
||||
and takes the most restrictive, with **no notion of one limit out-ranking
|
||||
another**; a peak `lo = −300 W` against a shaping `hi = −1000 W` is `lo > hi`,
|
||||
which resolves to **0 W — the battery parked, in the one quarter of the month
|
||||
that sets the bill**. That is the exact failure `peakguard.shaping_suspended()`
|
||||
exists to prevent, and the only way to close it would be to key that
|
||||
suppression on "a claim exists" — which, on every site this card is about,
|
||||
means the maintenance charge-only shaping is suspended **permanently**. A
|
||||
silent, large change to a different subsystem is not a price this card should
|
||||
pay.
|
||||
2. It changes the meaning of `PeakDecision.engaged` at five call sites outside
|
||||
this module — `arbitrage.guard_state()`, `shaping_suspended()`,
|
||||
`claim()`, `main.py`'s edge-logged action line and `main.py`'s status row —
|
||||
each of which today means "the guard is HOLDING" and would silently start
|
||||
meaning "a claim exists".
|
||||
|
||||
`test_peakguard.py` part 5's sweep asserts **no negative floor, ever**, and the
|
||||
reason it gives ("a `lo` limit is incapable of capping discharge or export only
|
||||
while it is non-negative") is, strictly, not the true reason — a `lo` of any sign
|
||||
caps neither. The invariant is still right and is still worth holding; §2b above
|
||||
is the argument that actually supports it, and it is recorded here rather than
|
||||
left for the next person to re-derive.
|
||||
|
||||
### 2c. A backoff, cooldown or hysteresis constant in `arbitrage.py` — rejected
|
||||
The card asks whether the second half of the fix belongs in arbitrage: *"a trade
|
||||
refused at 14:59 and re-armed at 15:00 has learned nothing from the refusal."*
|
||||
It does belong there, but as a **size**, not as a memory. `arbitrage.py`'s
|
||||
hysteresis note is explicit that the switching decision is "which hour is it" and
|
||||
that **no timer is needed and none is invented**; `peakguard.py`'s design note
|
||||
spends a paragraph on why it carries no hysteresis constant. A cooldown would be
|
||||
a second control loop compensating for a limit the first one declined to file,
|
||||
and its constant would outlive whatever it was tuned against. The trade now
|
||||
re-arms at `ceiling − load` instead of at `max_w`, which is what "learning from
|
||||
the refusal" means when the refusal is a measurement.
|
||||
|
||||
## 3. What was done, and the precedent it follows
|
||||
|
||||
`control.maintenance_charge_floor()` has capped MAINTENANCE charging at *"the
|
||||
headroom left under the site's cap"* since the loop was written, and its
|
||||
docstring says why:
|
||||
|
||||
> "A maintenance charge is the only thing this system does that is big enough and
|
||||
> long enough to set that peak, so it is capped by the headroom left under the
|
||||
> site's cap."
|
||||
|
||||
⚠️ **THAT SENTENCE STOPPED BEING TRUE WHEN OPT-04 LANDED.** Price arbitrage is a
|
||||
second thing that is big enough and long enough — it commands `max_w` for a whole
|
||||
tariff interval, deliberately, against the meter — and it was given no such cap.
|
||||
This card gives it the same shape, with one difference that matters:
|
||||
`maintenance_charge_floor()` sizes itself from `peak_forecast_entity`, which is
|
||||
OPTIONAL and empty on a default install — the exact hole SAFETY-25 had to close
|
||||
in `shaping_suspended()`. `charge_headroom_w()` comes off `decide()`, which runs
|
||||
wherever P1 does.
|
||||
|
||||
**The number is `wanted_w` read in the other direction.** `decide()` already
|
||||
computes `wanted = batt_w + excess` as the DISCHARGE that lands the quarter on the
|
||||
ceiling; a negative `wanted` is a permitted CHARGE of `−wanted`. No new
|
||||
arithmetic, no new constant.
|
||||
|
||||
Two properties make it safe to hand a strategy, and both are swept rather than
|
||||
argued (`test_peakguard.py` part 13):
|
||||
|
||||
* ⚠️ **IT IS INVARIANT IN THE BATTERY.** Raise the charge by dW and the meter
|
||||
rises by dW, so `excess` rises by exactly dW while `batt_w` falls by dW:
|
||||
`wanted` does not move. Measured across `batt_w` from −5000 W to +2000 W on one
|
||||
banked quarter — the headroom is 1350.0 W at every one of the six points while
|
||||
the `excess` those runs see moves through six distinct values. It is a
|
||||
**feed-forward** number, so consuming it adds no feedback path around the plant.
|
||||
The fixed point is `charge = ceiling − load`, with the meter ON the ceiling and
|
||||
`wanted` parked a whole `ceiling − load` clear of the engagement boundary.
|
||||
* **HOLDING IMPLIES ZERO OR UNKNOWN.** Across 1080 swept combinations, not one
|
||||
ENGAGED decision answers a positive headroom, so the function can never hand a
|
||||
caller permission the guard's own `lo` is at that instant refusing.
|
||||
|
||||
## 4. After, on the same rig, same command, same checkout
|
||||
|
||||
| `peak_cap_w` | house | onsets/h | grid swing | energy bought | billed quarters (W) |
|
||||
|---|---|---|---|---|---|
|
||||
| 1500 | 1200 W | 28 → **1** | 3655.5 → **282.0 W** | 180.0 → **285.2 Wh** | **1500.0 / 1500.0 / 1500.0** |
|
||||
| 3500 | 1800 W | 8 → **1** | 3672.5 → 1687.6 W | 1652.9 → 1616.1 Wh | **3500.0 / 3500.0 / 3500.0** |
|
||||
| 3500 | 3000 W | 32 → **1** | 3798.0 → **474.7 W** | 482.9 → 475.3 Wh | **3500.0 / 3500.0 / 3500.0** |
|
||||
| 5000 | 1200 W | 1 → 1 | **identical** | **identical** | **identical** |
|
||||
|
||||
* **One onset** means the trade starts once and runs for the whole window. The
|
||||
battery is trading 100 % of the hour where it used to trade 43 %, 92 % and 54 %.
|
||||
* **Every billed quarter lands exactly on the cap and none over it**, where every
|
||||
quarter in the three biting rows used to finish over.
|
||||
* **The money.** At 1500/1200 the site buys **58 % MORE** energy, because a
|
||||
continuous 300 W trade beats a 2000 W trade that is cancelled for 57 % of the
|
||||
hour. At the two shipped-default rows it buys **2.2 % and 1.6 % less** — and in
|
||||
exchange the worst quarter drops from 59 W over the cap to 0 W over it. The
|
||||
capacity tariff bills the month's single worst quarter with no averaging and no
|
||||
forgiveness (specs.md:583), so that is not a trade-off, it is the ordering
|
||||
§10.1 asks for.
|
||||
* The remaining 1687.6 W at 3500/1800 is the opening **ramp**, not a cycle: the
|
||||
pack goes from 0 to 1700 W of charge in about ten seconds and the meter with
|
||||
it. One onset, no export, no reversal.
|
||||
* The last row is bit-identical before and after. **This card costs nothing on
|
||||
the installs it is not about.**
|
||||
|
||||
## 5. What this does NOT fix, with sizes
|
||||
|
||||
* **TEST-23 finding 1 — the export overshoot at the END of a trade** (356–938 W,
|
||||
≈0.37 × `max_w`) is untouched and is a different card. It happens when the
|
||||
cheap interval ends and the grid-following loop takes back an actuator that was
|
||||
holding a charge; nothing here changes the handover.
|
||||
* **A house whose load ALONE exceeds the cap** (`load > peak_cap_w`) still puts
|
||||
`wanted > 0`, still engages the guard, and still refuses the trade outright
|
||||
through the interlock — correctly, since you cannot buy in a quarter you are
|
||||
already over on. The loop then drives to grid = 0 rather than to grid =
|
||||
ceiling, which is more discharge than the guard asked for. Not swept here: all
|
||||
four (cap, load) pairs on the record have `load < cap`.
|
||||
* **`arbitrage.claim()` still files the SIZED number, but the ARBITER can clamp
|
||||
it further** and the strategy is not told. The reason line names the guard's
|
||||
headroom, not the arbiter's `bound_by`. Pre-existing; not widened.
|
||||
* **The container leg was not re-run.** `hadrive.py` needs `test23s3-addon`
|
||||
started, and that container is deliberately stopped because it is a second
|
||||
writer on the setpoint entity under measurement. The in-process rig's twelve
|
||||
transcribed lines are pinned by `test_arbitrage.py` 3b's AST check on
|
||||
`main.py`'s call site, which is the line this card adds to them.
|
||||
@@ -601,6 +601,94 @@ behind it would trip the firmware watchdog on a system that is working fine.
|
||||
| `site_sign_disagree_w` | 300 | **Two or more inverters only.** Threshold for the site-wide check - the sum of the commands against the meter. The same 300 W as `sign_disagree_w`, for the same reason: near zero the sign is noise |
|
||||
| `site_sign_disagree_s` | 325 | **Two or more inverters only.** How long the site's total command and the meter must stay opposed before every inverter is parked. Longer than `sign_disagree_s` because the command has to cross zero over a rail that is the sum of the roster, at a `slew_w` that is not - measured at 110 s with one inverter and 215 s with two |
|
||||
| `delivery_hold_s` | 185 | **Two or more inverters only.** How long one inverter may stand at a discharge share it is not producing - short by more than `saturation_w`, with no reason this add-on can read - while at least one sibling is **not** in that state, before it is named. **It reports; it does not act.** Nothing is commanded differently and the site goes on running short by that unit's share |
|
||||
| `shadow_mode` | `auto` | **Run every decision and command nothing.** `auto` = shadow mode while control is stopped, ordinary control once you press Start; `on` = shadow mode always; `off` = ordinary control. See *Shadow mode* below |
|
||||
|
||||
#### Shadow mode (`shadow_mode`, SAFETY-10)
|
||||
|
||||
Shadow mode runs the **whole** decision path — the price strategy, the capacity
|
||||
guard, the maintenance shaping, the grid-following loop, the arbiter that ranks
|
||||
them, SAFETY-28's authorisation gate and SAFETY-03's clamp — and **sends nothing
|
||||
to the inverter**. It is how you find out what this add-on *would* do on a site
|
||||
before you let it do it.
|
||||
|
||||
Every defect in the optimiser that this project has found was invisible from
|
||||
outside while it was happening: a price lookup answering for the wrong
|
||||
quarter-hour, a trade against a binding capacity cap that ran 28 charge onsets
|
||||
in an hour, an SoC ceiling churning 598 Wh to gain 310 Wh. Each one was paid for
|
||||
at the meter first and noticed afterwards. Shadow mode is the surface that
|
||||
would have shown all three on the day.
|
||||
|
||||
**What "commands nothing" means, exactly.** Every inverter is held at **0 W**,
|
||||
written by the ordinary single writer and refreshed on the ordinary heartbeat.
|
||||
It is not silence. ⚠️ **The inverter holds its last command forever** — it has
|
||||
no meter timeout — so a mode that simply stopped writing would leave whatever
|
||||
was standing when you switched it on standing for as long as you left it on,
|
||||
under a page saying nothing was being commanded. Refreshing 0 W is also what
|
||||
the ESP32's 30 s stale-input watchdog requires of us: going quiet would put
|
||||
that board into a *tripped watchdog* state for the whole run, which is an alarm
|
||||
being used as a mode.
|
||||
|
||||
**The three values.**
|
||||
|
||||
| value | what happens |
|
||||
|---|---|
|
||||
| `auto` | **the shipped default.** Shadow mode while control is **stopped**; ordinary control once control is **started**. A new install ships `auto_start: false`, so it comes up in shadow mode and observes before it ever commands anything. An install that is already controlling is started, so nothing about it changes |
|
||||
| `on` | shadow mode **always**, whatever the *Start / stop control* button says. This is the one to pick to watch an armed site for a day — the loop runs, arbitrage decides, the peak guard files its claims, and the battery does not move |
|
||||
| `off` | ordinary control |
|
||||
|
||||
⚠️ **Existing installs are not changed.** The default is `auto` rather than a
|
||||
boolean `true` precisely because a boolean would have changed them: the
|
||||
Supervisor composes an add-on's options as *its defaults, overlaid with your
|
||||
stored options*, so a new key with a new default reaches every install on the
|
||||
next update. `shadow_mode: true` would have silently stopped a battery that is
|
||||
regulating today, and the only symptom would be a battery that stopped doing
|
||||
anything.
|
||||
|
||||
⚠️ **Under `auto`, pressing *Start* leaves shadow mode.** That is the point of
|
||||
`auto` — the button means "control the battery". Set `on` if you want the
|
||||
decisions recorded while the loop runs.
|
||||
|
||||
**What you get out of it.** The status page carries a red-amber banner saying
|
||||
the battery is not being controlled, a `Shadow mode` row saying which rung
|
||||
decided, what it **would have commanded** and why, and the `Why` row with the
|
||||
arbiter's own sentence. The action log gets one line each time the decision
|
||||
changes — the winner or the watts — rather than one per cycle, so a 40-row log
|
||||
still contains the context of what it found. MQTT reports `status: shadow`.
|
||||
|
||||
**The failsafes.** The sign watchdogs (SAFETY-02/30) are **inert**: they grade
|
||||
what this controller has standing on the wire, and that is 0 W, so they cannot
|
||||
arm. That is deliberate and it is the single most important decision in this
|
||||
feature — fed the shadow decision instead they would disagree with a meter that
|
||||
never saw it, and **latch a trip that survives into live operation and a
|
||||
restart**. The clamp (SAFETY-03), the write-authorisation gate (SAFETY-28), the
|
||||
frozen-meter alarm (SAFETY-18) and the capacity guard all **observe**: they run
|
||||
on the number the decision path produced, so a shadow run can tell you the
|
||||
clamp would have engaged. The circulation (SAFETY-31) and delivery (SAFETY-42)
|
||||
watchdogs observe and may legitimately latch, because their evidence is
|
||||
*measured* power, not a command. The operator stop is enforced at the wire
|
||||
instead of as a claim, so that the recorded decision is the real one.
|
||||
|
||||
⚠️ **A latch that was already up stays up.** Shadow mode does not clear
|
||||
anything. The banner names any standing latch and goes red for it, because a
|
||||
latch that is up while the controller is inert is up the moment it stops being
|
||||
inert.
|
||||
|
||||
⚠️ **Maintenance is unchanged.** The maintenance state machines are ticked on
|
||||
every cycle whether control is started or not, so they already run against a
|
||||
battery that does not move on a stopped install. Shadow mode inherits that
|
||||
exactly; it neither improves it nor makes it worse.
|
||||
|
||||
⚠️ **What a shadow run will NOT tell you.** The controller's carried command is
|
||||
re-seeded to the 0 W standing on the wire at the end of every shadow cycle —
|
||||
that is what makes turning shadow mode off safe, because the loop then resumes
|
||||
from where the battery actually is. The consequence is that the
|
||||
**grid-following loop's** recorded decision is **one slew step** and stays
|
||||
there: a shadow run answers *"what would it command now"*, not *"what
|
||||
trajectory would it have followed"*, because the trajectory depends on a
|
||||
battery responding and none did. The **strategies** are unaffected — price
|
||||
arbitrage, the capacity guard and maintenance all ask for a fixed power from
|
||||
inputs that do not depend on what the battery did — so a shadow run does show
|
||||
you the trades, the peak-guard engagements and the SoC-limit behaviour.
|
||||
|
||||
#### The sign-disagreement failsafe
|
||||
|
||||
@@ -979,6 +1067,7 @@ What exists today, and what does not:
|
||||
|---|---|
|
||||
| `max_w` bounds the magnitude | ✅ — but the exposure IS the magnitude |
|
||||
| Maintenance charging capped under `peak_cap_w` | ✅ |
|
||||
| **Arbitrage charging capped under `peak_cap_w`** | ✅ — SAFETY-45, sized to the guard's own MEASURED headroom rather than to `peak_forecast_entity` |
|
||||
| **Loop capped under `peak_cap_w`** | ✅ — SAFETY-07, on every `meter_source` but `off` |
|
||||
| Frozen meter detected | ✅ on `homewizard_local` only, **alarm only** |
|
||||
| Frozen meter *stopped* | ✅ — SAFETY-07 forbids importing while the meter is frozen |
|
||||
@@ -1041,6 +1130,19 @@ projected over — raises one notification (`goodwe_peak_saturated`), because th
|
||||
is the one state where the money will be spent and shedding load is the only
|
||||
thing left that changes the bill.
|
||||
|
||||
**And it sizes a price-driven charge, not only a forced discharge (SAFETY-45).**
|
||||
The same arithmetic read the other way answers *"how hard may this site charge
|
||||
without putting the quarter over"* — `peakguard.charge_headroom_w()` — and
|
||||
`arbitrage.decide()` sizes its buy leg to it. Before that, a trade commanded
|
||||
`max_w` until the projection rose far enough to engage the guard, at which point
|
||||
the interlock cancelled the trade outright, the loop took the actuator, the
|
||||
projection collapsed and the trade came back at `max_w`: **28 charge onsets in
|
||||
one hour** on TEST-23 stage 3's closed rig, with the grid swinging −456 to
|
||||
+3200 W and every billed quarter finishing over the cap. It is one onset now,
|
||||
the trade runs continuously at the affordable rate, and the billed quarters land
|
||||
**on** the cap. ⚠️ The guard is what changed *around* arbitrage; `decide()`
|
||||
itself is untouched, so nothing above this line is different.
|
||||
|
||||
**No new option for the CEILING.** It is `peak_cap_w`, which already shipped. The
|
||||
coverage threshold is `meter_max_age_s`, the freeze predicate is
|
||||
`meter_freeze_s`, and the achievable discharge comes from `max_w` and the device
|
||||
|
||||
@@ -184,6 +184,17 @@ IDLE_OFF_PEAK_HOUR = "this hour is neither the buy hour nor the sell hour"
|
||||
IDLE_NO_SIZE = (
|
||||
"no pack's state of charge permits this side of the trade, so it is sized "
|
||||
"at 0 W - and a 0 W arbitrage claim is a park order, not a trade")
|
||||
# SAFETY-45. THE BUY LEG'S SIZE, AND ONLY THE BUY LEG'S - §9.1: "Discharge and
|
||||
# export are never capped by the peak guard; only charging and import are."
|
||||
IDLE_NO_HEADROOM = (
|
||||
"the capacity-tariff guard has measured this billed quarter and it can "
|
||||
"afford no charging at all, so a trade of any size would push it over the "
|
||||
"ceiling - and a 0 W arbitrage claim is a park order, not a trade")
|
||||
IDLE_HEADROOM_UNMEASURED = (
|
||||
"the capacity-tariff guard did not size this quarter's charging headroom "
|
||||
"this cycle, and an UNMEASURED headroom is not an unlimited one - charging "
|
||||
"creates the billed quantity (§9.1) and nothing is measuring the quarter "
|
||||
"this one would land in")
|
||||
NEGATIVE_PRICE = (
|
||||
"§17: the sell hour is priced BELOW ZERO, so discharging into it would give "
|
||||
"energy away and pay for the privilege. Arbitrage must not export at a "
|
||||
@@ -303,7 +314,7 @@ def _point_at(plan, when: datetime):
|
||||
return None
|
||||
|
||||
|
||||
def decide(plan, now: datetime, *, peak_guard_active, soc,
|
||||
def decide(plan, now: datetime, *, peak_guard_active, charge_headroom_w, soc,
|
||||
min_spread_eur_kwh, uncertainty, charge_w, discharge_w,
|
||||
soc_floor_pct, soc_ceiling_pct) -> ArbitrageDecision:
|
||||
"""Should the battery trade this cycle, and how hard.
|
||||
@@ -314,6 +325,18 @@ def decide(plan, now: datetime, *, peak_guard_active, soc,
|
||||
None refuses, because the alternative is a strategy that creates the billed
|
||||
quantity while the thing that would have limited it is switched off.
|
||||
|
||||
⚠️ `charge_headroom_w` IS SAFETY-45's SECOND, CONTINUOUS ANSWER FROM THE
|
||||
SAME GUARD, AND IT IS NOT A DUPLICATE OF THE FIRST. `peak_guard_active` is a
|
||||
SWITCH - it says whether the guard is holding - and a switch keyed on a
|
||||
continuous quantity is what made the loop oscillate: the guard engaged at a
|
||||
5 W floor, this module refused the whole trade, the loop took the actuator,
|
||||
the meter fell, the guard released and the trade re-armed AT FULL POWER
|
||||
130 s later. 28 times an hour, measured. `peakguard.charge_headroom_w()` is
|
||||
the watts the billed quarter can still afford; sizing the buy leg to it means
|
||||
the trade is CLAMPED rather than switched, which is the same shape
|
||||
`control.maintenance_charge_floor()` has always given a maintenance charge.
|
||||
⚠️ None IS NOT UNLIMITED here either - see IDLE_HEADROOM_UNMEASURED.
|
||||
|
||||
⚠️ EVERY OTHER ARGUMENT IS KEYWORD-ONLY AND HAS NO DEFAULT, for
|
||||
`TariffPlan.arbitrage()`'s reason. A defaulted `soc_floor_pct` is a reserve
|
||||
floor this module asserted rather than one the operator configured, and the
|
||||
@@ -330,10 +353,12 @@ def decide(plan, now: datetime, *, peak_guard_active, soc,
|
||||
return verdict.match(
|
||||
refused=lambda v: _idle(v.reason),
|
||||
allowed=lambda v: _act(plan, now, v, soc, charge_w, discharge_w,
|
||||
soc_floor_pct, soc_ceiling_pct))
|
||||
soc_floor_pct, soc_ceiling_pct,
|
||||
charge_headroom_w))
|
||||
|
||||
|
||||
def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct):
|
||||
def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct,
|
||||
headroom_w):
|
||||
"""The permitted case: which hour is this, and may the pack do it."""
|
||||
here = _point_at(plan, now)
|
||||
if here is None:
|
||||
@@ -403,13 +428,44 @@ def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct):
|
||||
f"nowhere to put the cheap energy", **common)
|
||||
if not abs(float(charge_w)) > 0.0:
|
||||
return _idle(IDLE_NO_SIZE, **common)
|
||||
# SAFETY-45. THE BILLED QUARTER IS ASKED LAST, AND THE PLACEMENT IS
|
||||
# DELIBERATE: every refusal that existed before this card keeps the
|
||||
# precedence it had, so no sentence an operator already reads changes when
|
||||
# it fires, and the two added here are placed where they cannot displace
|
||||
# one. The pack's reasons come first because they are properties of the
|
||||
# hardware in the cupboard; this one is a property of the fifteen minutes
|
||||
# the trade would land in.
|
||||
if headroom_w is None:
|
||||
# ⚠️ NOT "the guard is clear". This is `guard_state()`'s None argument
|
||||
# one layer down: a headroom nothing measured is not an unlimited one,
|
||||
# and charging at max_w creates the billed quantity (§9.1).
|
||||
return _idle(IDLE_HEADROOM_UNMEASURED, **common)
|
||||
asked_w = abs(float(charge_w))
|
||||
size_w = min(asked_w, max(0.0, float(headroom_w)))
|
||||
if not size_w > 0.0:
|
||||
# ⚠️ NOT IDLE_NO_SIZE, WHICH IS THE LINE ABOVE AND BLAMES THE PACKS.
|
||||
# `asked_w > 0` is already established here, so the pack may be empty
|
||||
# and willing and it is the billed quarter that has run out. A refusal
|
||||
# naming the wrong subsystem sends an operator to the wrong page
|
||||
# (§10.2), and these two are a whole quarter-hour apart in what they
|
||||
# ask a human to do about them.
|
||||
return _idle(IDLE_NO_HEADROOM, **common)
|
||||
# ⚠️ THE SENTENCE CARRIES BOTH NUMBERS IN THEIR OWN SLOTS, not one figure
|
||||
# twice. MUTATION.md habit 14: two values in one sentence can be transposed
|
||||
# by a ZERO-BYTE edit that no byte delta and no shape pin can see, so the
|
||||
# trade's own size and the guard's headroom are each named by the literal
|
||||
# text around them.
|
||||
capped = size_w < asked_w
|
||||
return ArbitrageDecision(
|
||||
action=CHARGE, power_w=-abs(float(charge_w)),
|
||||
action=CHARGE, power_w=-size_w,
|
||||
reason=(f"{CHARGE}: this is the cheapest firm hour at "
|
||||
f"{price:.4f} EUR/kWh, {v.spread_eur_kwh:.4f} below the dearest "
|
||||
f"and clear of the {v.required_spread_eur_kwh:.4f} this cycle "
|
||||
f"had to cover; charging {abs(float(charge_w)):.0f} W from "
|
||||
f"{soc:g} %"),
|
||||
f"had to cover; charging {size_w:.0f} W from {soc:g} %"
|
||||
+ (f" - SIZED BY THE CAPACITY-TARIFF GUARD: the trade asked for "
|
||||
f"{asked_w:.0f} W and this billed quarter can afford "
|
||||
f"{float(headroom_w):.0f} W (§9.1, §10.1 priority 2)"
|
||||
if capped else "")),
|
||||
spread_eur_kwh=v.spread_eur_kwh,
|
||||
required_eur_kwh=v.required_spread_eur_kwh,
|
||||
price_now_eur_kwh=price)
|
||||
|
||||
@@ -66,6 +66,7 @@ from .mqtt import (MqttPublisher, announced_units, unit_slugs,
|
||||
unit_state_key)
|
||||
from . import peakguard
|
||||
from . import packshare
|
||||
from . import shadow
|
||||
from .p1 import P1Ingest, build_source, is_enabled
|
||||
from .price import Uncertainty, price_option, provider_configured
|
||||
from .price_history import PriceHistory
|
||||
@@ -830,6 +831,24 @@ class Controller:
|
||||
|
||||
# live state
|
||||
self.auto = bool(store.data.get("auto", opts.get("auto_start", False)))
|
||||
# --- SAFETY-10 -------------------------------------------------------
|
||||
# What the decision path reached on the last shadow cycle, in W, or
|
||||
# None before the first one. ⚠️ IT IS KEPT SEPARATELY FROM
|
||||
# `self.target` BECAUSE THEY ARE DIFFERENT FACTS: `self.target` is what
|
||||
# is STANDING ON THE WIRE - held at `shadow.WIRE_W` for the whole of a
|
||||
# shadow run, and re-seeded to it at the end of every shadow cycle so
|
||||
# the loop and the sign watchdogs track reality - and this is what a
|
||||
# live controller WOULD have put there. Folding them into one field is
|
||||
# how a shadow run starts telling an operator a number nothing is
|
||||
# doing.
|
||||
self.shadow_would_w = None
|
||||
# Edge state for the action log, both of them. `_shadow_was` is None
|
||||
# until the first cycle, so an install that comes up IN shadow mode
|
||||
# says so in the log it will be read from rather than leaving the
|
||||
# operator to infer it from a page nobody is looking at yet. Coming up
|
||||
# LIVE is silent - see `_shadow_settle()`, which says why.
|
||||
self._shadow_was = None
|
||||
self._shadow_winner = None
|
||||
self.target = 0.0
|
||||
self.sat_count = 0
|
||||
self.i_w = 0.0 # the loop's integrator, carried between cycles
|
||||
@@ -1739,6 +1758,42 @@ class Controller:
|
||||
"reports a different value.",
|
||||
inv.name, inv.batt_fresh.reason)
|
||||
|
||||
@property
|
||||
def shadow(self) -> bool:
|
||||
"""SAFETY-10. Is the battery being left alone right now?
|
||||
|
||||
⚠️ A PROPERTY, NOT A FIELD, AND FOR THE REASON `self.units` IS ONE.
|
||||
Three surfaces ask this question at three different moments - the
|
||||
cycle, the write, and the status page rendered between two cycles - and
|
||||
a cached flag is a fourth answer that can disagree with the option and
|
||||
the button it is derived from. Derived, they cannot.
|
||||
|
||||
⚠️ AND THE WRITE GATE ASKS THIS, NOT A PARAMETER PASSED DOWN TO IT. A
|
||||
suppression that had to be threaded through `write_setpoint()` would be
|
||||
absent from every call site that forgot it - the heartbeat, the stop
|
||||
button, `shutdown()` - which is exactly the shape of hole this add-on's
|
||||
single choke point exists to close.
|
||||
"""
|
||||
return shadow.engaged(self.o, control_started=self.auto)
|
||||
|
||||
def shadow_latches(self) -> tuple:
|
||||
"""The failsafe latches that are UP, named, for the shadow banner.
|
||||
|
||||
A latch that is standing while the controller is inert is standing when
|
||||
it stops being inert. `shadow.banner()` carries them so an operator who
|
||||
turns shadow mode off is not handed a battery that will not move and a
|
||||
page that never mentioned why.
|
||||
"""
|
||||
out = []
|
||||
if self.circ_wd.tripped:
|
||||
out.append("circulating power")
|
||||
if self.site_sign_wd.tripped and len(self.inverters) > 1:
|
||||
out.append("site sign watchdog")
|
||||
for inv in self.inverters:
|
||||
if inv.sign_wd.tripped:
|
||||
out.append(f"{inv.name} sign watchdog")
|
||||
return tuple(out)
|
||||
|
||||
def write_refusal(self, value: float, inv=None) -> str | None:
|
||||
"""Why `value` may NOT be written to `inv` right now, or None if it may.
|
||||
|
||||
@@ -1930,6 +1985,40 @@ class Controller:
|
||||
self.log_event(f"{inv.name}: {result.describe()}")
|
||||
value = result.applied_w
|
||||
|
||||
# --- SAFETY-10: AND THIS IS THE LAST THING BEFORE THE WIRE -----------
|
||||
# Shadow mode runs the whole decision path and commands nothing. The
|
||||
# suppression is HERE, in the one method every write in this add-on
|
||||
# reaches - the cycle, the heartbeat, the stop button, shutdown() and
|
||||
# maint_abort() alike - so there is no call site that can route round
|
||||
# it. app/shadow.py carries the whole argument; three things about the
|
||||
# placement belong here:
|
||||
#
|
||||
# ⚠️ IT IS A SUBSTITUTION, NOT A RETURN, exactly like the two refusals
|
||||
# above it. Returning would leave the inverter LATCHED ON ITS LAST
|
||||
# COMMAND with the ESP32's heartbeat still being fed - a battery held
|
||||
# at whatever it was doing when shadow mode was switched on, under a
|
||||
# status page saying nothing is being commanded. That is the failure
|
||||
# this add-on keeps finding, and shadow mode must not be a new way to
|
||||
# reach it. `shadow.WIRE_W` is 0.0 W and it is REFRESHED on the
|
||||
# ordinary heartbeat, which is also what firmware/goodwe-master.yaml's
|
||||
# 30 s stale-input watchdog requires of us.
|
||||
#
|
||||
# ⚠️ IT IS BELOW SAFETY-28's GATE AND BELOW SAFETY-03's CLAMP, so both
|
||||
# still grade the number the decision path actually produced. A shadow
|
||||
# run that could not say "it would have hit the rating here" would be
|
||||
# answering a different question from the one it is for.
|
||||
#
|
||||
# ⚠️ IT IS NOT A SECOND WRITER. No claim is filed, no transport is
|
||||
# opened and no arithmetic of its own reaches the wire: one actuator,
|
||||
# one writer, and this is that writer emitting the value it emits for
|
||||
# every other refusal.
|
||||
if self.shadow and value != shadow.WIRE_W:
|
||||
_LOG.info("SHADOW MODE: not commanding %+.0f W to %s - holding "
|
||||
"%+.0f W. The decision was reached and recorded; "
|
||||
"nothing was sent to the inverter.",
|
||||
value, inv.name, shadow.WIRE_W)
|
||||
value = shadow.WIRE_W
|
||||
|
||||
changed = (inv.last_write is None or value != inv.last_write)
|
||||
if not (changed or force):
|
||||
return
|
||||
@@ -2549,7 +2638,16 @@ class Controller:
|
||||
# operator switching control off for the whole site; "inputs missing" is
|
||||
# the SITE's own telemetry gone - the meter this controller regulates
|
||||
# against. Neither is about a pack, and both must stop every inverter.
|
||||
if not self.auto:
|
||||
# ⚠️ SAFETY-10: `and not self.shadow`, AND IT IS THE ONE FAILSAFE THIS
|
||||
# CARD CHANGES. `P_SAFETY` out-ranks every other claim, so leaving the
|
||||
# stop claim in while shadow mode is engaged would make the recorded
|
||||
# decision "stopped" on every cycle - a shadow run that answers the
|
||||
# wrong question, which is the same as no shadow run. The actuator ends
|
||||
# at the same number either way, and the substitution in `_write_unit()`
|
||||
# that replaces it is STRICTLY STRONGER than this claim: a claim can be
|
||||
# out-ranked by a higher priority, and the wire gate cannot be
|
||||
# out-ranked by anything.
|
||||
if not self.auto and not self.shadow:
|
||||
claims.append(Claim.set("safety", P_SAFETY, 0.0, "stopped",
|
||||
actuator=self.actuator_of("safety")))
|
||||
elif not self.inputs_ok:
|
||||
@@ -2726,6 +2824,22 @@ class Controller:
|
||||
self.arb = arbitrage.decide(
|
||||
self.fresh_tariff_plan(now), now,
|
||||
peak_guard_active=arbitrage.guard_state(self.peak_guard),
|
||||
# SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS
|
||||
# ONE. `guard_state()` is a switch and it was the whole loop:
|
||||
# the guard engaged on a 5 W floor, the trade was refused
|
||||
# outright, the loop took the actuator, the meter fell, the
|
||||
# guard released and the trade came back AT max_w. Measured on
|
||||
# TEST-23 stage 3 at the shipped peak_cap_w/max_w: 28 charge
|
||||
# onsets an hour, grid -456 <-> +3200 W. This is the watts the
|
||||
# billed quarter can still afford, so the buy leg is CLAMPED
|
||||
# instead - the shape control.maintenance_charge_floor() has
|
||||
# always given a maintenance charge, off the MEASURED guard
|
||||
# rather than off the optional peak_forecast_entity.
|
||||
# ⚠️ SAME ORDERING ARGUMENT AS THE LINE ABOVE: this reads the
|
||||
# peak block's conclusion, ~50 lines up, so it must stay after
|
||||
# it. Evaluated earlier it would size this quarter's trade from
|
||||
# the previous cycle's quarter.
|
||||
charge_headroom_w=peakguard.charge_headroom_w(self.peak_guard),
|
||||
# The emptiest pack again, and for the sell side that is the
|
||||
# right reduction. ⚠️ THE BUY SIDE WANTS THE FULLEST, and there
|
||||
# is one `soc` argument - `pack_floor_soc` names that residual
|
||||
@@ -2877,7 +2991,14 @@ class Controller:
|
||||
inv)))
|
||||
|
||||
# --- the grid-following loop -----------------------------------------
|
||||
if self.auto and self.inputs_ok:
|
||||
# ⚠️ SAFETY-10: `or self.shadow`. The loop is the leg a shadow run most
|
||||
# needs and the one that is switched off by `auto_start: false`, so
|
||||
# without this an install in `auto` shadow mode would record every
|
||||
# strategy's decision and a permanent silence where the grid-following
|
||||
# loop should be. It is safe because the loop's `prev_w` is
|
||||
# `self.target`, which the end of this method re-seeds to what is
|
||||
# actually standing on the wire.
|
||||
if (self.auto or self.shadow) and self.inputs_ok:
|
||||
# ⚠️ prev is the ARBITER's last output, not the loop's own last
|
||||
# wish. If something outranked the loop, that is what the hardware
|
||||
# actually did, and the controller must track reality or it jumps
|
||||
@@ -3211,6 +3332,116 @@ class Controller:
|
||||
# reads only `self.p1`, which no line in this method writes.
|
||||
self.peak.sync(self.p1)
|
||||
|
||||
# --- SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS -----
|
||||
# Every guard above has now read `self.target` - the resolved intent -
|
||||
# and SAFETY-18 in particular grades exactly that. Re-seeding before
|
||||
# them would hand each one a 0 W that no decision produced. Re-seeding
|
||||
# AFTER them hands the NEXT cycle, and the sign watchdogs, what is
|
||||
# actually standing on the wire. See `_shadow_settle()`.
|
||||
self._shadow_settle(resolution)
|
||||
|
||||
def _shadow_settle(self, resolution) -> None:
|
||||
"""SAFETY-10. Record the decision, then re-seed the carried command.
|
||||
|
||||
TWO JOBS, AND THEY ARE IN THIS ORDER BECAUSE THE SECOND DESTROYS THE
|
||||
FIRST'S EVIDENCE.
|
||||
|
||||
1. THE RECORD. A shadow run is only worth running if it answers "what
|
||||
would it have done, and why". `self.shadow_would_w` and
|
||||
`Resolution.explain()` are that answer, and the action log gets one
|
||||
line per CHANGE OF DECISION rather than one per cycle - the log
|
||||
holds 40 rows, and a level-logged shadow run would flush the context
|
||||
of its own findings inside four minutes at a 15 s cycle floor. The
|
||||
same edge rule the peak guard and the arbitrage strategy already
|
||||
use, for the same reason.
|
||||
|
||||
2. THE RE-SEED. `self.target` and each `inv.target` are set back to
|
||||
`shadow.WIRE_W` - what the write gate actually put on the wire.
|
||||
|
||||
⚠️ WHY THE RE-SEED IS A SAFETY PROPERTY AND NOT BOOKKEEPING. Three
|
||||
machines read the carried command as a statement about the HARDWARE:
|
||||
|
||||
* `compute(prev_w=self.target, ...)` - the loop's slew limiter and
|
||||
its integrator. Left holding a shadow decision, the first cycle
|
||||
after shadow mode is turned off would slew from a base that never
|
||||
existed: up to a full `slew_w` step onto a battery sitting at 0 W.
|
||||
Re-seeded, the exit is safe BY CONSTRUCTION and needs no separate
|
||||
transition code - the carried command already equals the standing
|
||||
one.
|
||||
* `Inverter.standing_w()`, which is what SAFETY-02/30's sign
|
||||
watchdogs grade. Fed a shadow decision they would compare a number
|
||||
against a meter that never saw it, disagree for as long as the
|
||||
decision asked for power, and LATCH A TRIP THAT SURVIVES INTO LIVE
|
||||
OPERATION AND A RESTART. Shadow mode would manufacture the failsafe
|
||||
it exists to help debug. ⚠️ THIS ONE IS ALREADY HELD BY THE WIRE
|
||||
GATE - `standing_w()` prefers `last_write`, and that is the 0.0 W
|
||||
the gate accepted - so the re-seed is the SECOND rung, covering
|
||||
the fallback before any write has been accepted. Two rungs
|
||||
answering one question is MUTATION.md's masking shape, and the
|
||||
mutation that reproduces the hazard has to defeat BOTH: driven
|
||||
singly, dropping this line leaves the detector inert and names
|
||||
nothing about the latch. Measured.
|
||||
* SAFETY-42's delivery watchdog compares `inv.target` against what
|
||||
the pack is producing. A share nothing was told to produce is a
|
||||
delinquency report on every cycle of every shadow run.
|
||||
|
||||
⚠️ AND EVERY CYCLE'S DECISION IS THEREFORE COMPUTED FROM WHERE THE
|
||||
PLANT REALLY IS, not from a counterfactual plant that drifts further
|
||||
from reality every tick. "What would this controller command NOW,
|
||||
given this meter and a battery at 0 W" is a true statement about the
|
||||
present; "what would the eleventh cycle of a run that never happened
|
||||
have commanded" is not a statement about anything.
|
||||
"""
|
||||
engaged = self.shadow
|
||||
if engaged != self._shadow_was:
|
||||
# ⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT. The
|
||||
# edge is against `None` on cycle one, and an install that comes up
|
||||
# CONTROLLING has nothing to report - a "shadow mode off" line at
|
||||
# every start is one more row of boilerplate in a 40-row log, and
|
||||
# it was measured pushing a real clamp episode's context out of
|
||||
# test_clamp.py part 2's ring. Coming up IN shadow mode is the
|
||||
# other direction and it is always worth a line: it is the log an
|
||||
# operator reads to find out why nothing is being commanded.
|
||||
first = self._shadow_was is None
|
||||
self._shadow_was = engaged
|
||||
if engaged:
|
||||
self.log_event(
|
||||
"SHADOW MODE ON - " + shadow.why(
|
||||
self.o, control_started=self.auto)
|
||||
+ f"; inverter held at {shadow.WIRE_W:.0f} W")
|
||||
_LOG.warning(
|
||||
"SAFETY-10 SHADOW MODE IS ON. The full decision path runs "
|
||||
"and NOTHING is commanded: every inverter is held at "
|
||||
"%+.0f W on the ordinary heartbeat. %s", shadow.WIRE_W,
|
||||
shadow.why(self.o, control_started=self.auto))
|
||||
elif not first:
|
||||
self.log_event(
|
||||
"SHADOW MODE OFF - the battery is being controlled again, "
|
||||
f"resuming from {shadow.WIRE_W:.0f} W")
|
||||
_LOG.warning(
|
||||
"SAFETY-10 shadow mode is OFF. This controller is "
|
||||
"commanding the battery again, starting from the "
|
||||
"%+.0f W that was standing on the wire.", shadow.WIRE_W)
|
||||
if not engaged:
|
||||
self.shadow_would_w = None
|
||||
self._shadow_winner = None
|
||||
return
|
||||
self.shadow_would_w = float(resolution.target_w)
|
||||
# ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision
|
||||
# that moves from the loop to the peak guard at the same number is a
|
||||
# different decision and the operator needs the line; a loop target
|
||||
# that wanders by a watt is not, and 15 s of those would be the whole
|
||||
# log.
|
||||
edge = (resolution.winner, round(float(resolution.target_w)))
|
||||
if edge != self._shadow_winner:
|
||||
self._shadow_winner = edge
|
||||
self.log_event(
|
||||
f"SHADOW: would have commanded {resolution.target_w:+.0f} W - "
|
||||
+ resolution.explain())
|
||||
self.target = shadow.WIRE_W
|
||||
for inv in self.inverters:
|
||||
inv.target = shadow.WIRE_W
|
||||
|
||||
async def check_output_clamp(self) -> None:
|
||||
"""SAFETY-03. Alarm whenever a clamp actually engaged this cycle.
|
||||
|
||||
@@ -4000,6 +4231,14 @@ class Controller:
|
||||
or (self.site_sign_wd.tripped
|
||||
and len(self.inverters) > 1)
|
||||
or self.circ_wd.tripped
|
||||
# SAFETY-10: "shadow" is its own value and not a
|
||||
# flavour of "stopped". A fleet dashboard reporting a
|
||||
# shadow install as `running` would be calling a
|
||||
# battery nobody is controlling healthy; one reporting
|
||||
# it as `stopped` would lose the fact that the decision
|
||||
# path is live and being recorded. ⚠️ BELOW `failsafe`:
|
||||
# a latch that is up is up, and shadow does not clear it.
|
||||
else "shadow" if self.shadow
|
||||
else "running" if self.auto else "stopped"),
|
||||
# SAFETY-31. ⚠️ MEASURED, not the allocation record - see
|
||||
# `site_circulating_w`. `publish()` drops None values, so a cycle
|
||||
@@ -4500,7 +4739,24 @@ class Controller:
|
||||
def status_payload(self) -> dict:
|
||||
checks = self.checks()
|
||||
bad = [c for c in checks if not c["ok"] and not c["warn"]]
|
||||
if self.circ_wd.tripped:
|
||||
# --- SAFETY-10, AND IT IS FIRST IN THE CASCADE -----------------------
|
||||
# "The battery is NOT being controlled" is the one sentence on this
|
||||
# page that may never be displaced by another condition. A banner that
|
||||
# can be out-ranked does not STATE a thing plainly; it states it
|
||||
# whenever nothing else is happening, which is the half of the time
|
||||
# nobody needs telling.
|
||||
#
|
||||
# ⚠️ AND IT CARRIES A STANDING LATCH RATHER THAN HIDING ONE. The three
|
||||
# `bad` branches below all say some version of "held at 0 W", which is
|
||||
# still true in shadow mode - but an operator who turns shadow mode off
|
||||
# with a latch up gets a battery that will not move and a page that
|
||||
# never mentioned it. `shadow.banner()` names the latch and goes red
|
||||
# for it, so nothing this cascade would have said is lost.
|
||||
_shadow = shadow.banner(self.o, control_started=self.auto,
|
||||
latched=self.shadow_latches())
|
||||
if _shadow is not None:
|
||||
level, banner = _shadow
|
||||
elif self.circ_wd.tripped:
|
||||
# ⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision. Both are
|
||||
# latched P_SAFETY stops, so the site is at 0 W either way and the
|
||||
# banner can only carry one sentence. This one goes first because it
|
||||
@@ -4600,6 +4856,16 @@ class Controller:
|
||||
("State of charge", "—" if self.pack_floor_soc is None
|
||||
else f"{self.pack_floor_soc:g} %"),
|
||||
("Commanded", w(self.target)),
|
||||
# SAFETY-10, and it sits BETWEEN the two rows it reconciles.
|
||||
# "Commanded 0 W" above and a "Why" below that explains a trade is
|
||||
# the exact pair an operator would otherwise have to guess at; this
|
||||
# row is what makes the two of them consistent, and it is rendered
|
||||
# in EVERY state - including `off`, where it says the battery IS
|
||||
# being controlled - because a surface whose ABSENCE is how you
|
||||
# learn something is a surface you have to already know about.
|
||||
("Shadow mode", shadow.words(
|
||||
self.o, control_started=self.auto,
|
||||
would_w=self.shadow_would_w, reason=self.reason)),
|
||||
("Why", self.reason),
|
||||
("Maintenance phase", self.maint.phase if len(self.inverters) <= 1
|
||||
else f"{self.maint.phase} ({self.maint_unit.name})"),
|
||||
|
||||
@@ -822,6 +822,145 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
|
||||
f"only give {ceil_top:.0f} W" if saturated else "")))
|
||||
|
||||
|
||||
def charge_headroom_w(decision) -> float | None:
|
||||
"""SAFETY-45. The hardest this SITE may charge without putting the billed
|
||||
quarter over the ceiling, in W, positive - or None when nothing measured it.
|
||||
|
||||
THE ONE PLACE THIS QUESTION IS ANSWERED, and it is public for the reason
|
||||
`discharge_permitted()`, `shaping_suspended()`, `guard_state()` and
|
||||
`looks_frozen()` are: the check that grades it has to assert on THE SHIPPED
|
||||
EXPRESSION, and a predicate transcribed into its own test is one copy plus a
|
||||
future disagreement about what the check means.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
THE DEFECT IT PREVENTS, AND IT IS NOT A NEW IDEA IN THIS REPOSITORY
|
||||
|
||||
`control.maintenance_charge_floor()` already caps MAINTENANCE charging at
|
||||
"the headroom left under the site's cap", and its docstring says why in
|
||||
words this card only has to widen:
|
||||
|
||||
"A maintenance charge is the only thing this system does that is big
|
||||
enough and long enough to set that peak, so it is capped by the
|
||||
headroom left under the site's cap."
|
||||
|
||||
⚠️ THAT SENTENCE STOPPED BEING TRUE WHEN OPT-04 LANDED. Price arbitrage is a
|
||||
SECOND thing that is big enough and long enough - it commands `max_w` for a
|
||||
whole tariff interval, deliberately, against the meter - and it was given no
|
||||
such cap. Measured on TEST-23 stage 3's closed rig at the shipped
|
||||
`peak_cap_w: 3500` / `max_w: 2000`: 28 charge onsets in one hour, mean period
|
||||
131 s, grid swinging -456 <-> +3200 W, on any house drawing over 1500 W in
|
||||
the cheapest quarter. §10.2: "an EMS that oscillates is worse than no EMS,
|
||||
both for hardware wear and - per §9.1 - for the peak it is trying to avoid."
|
||||
|
||||
⚠️ AND IT IS THE **MEASURED** GUARD, NOT `peak_forecast_entity`.
|
||||
`maintenance_charge_floor()` sizes itself from the forecast sensor, which is
|
||||
OPTIONAL and empty on a default install - the exact hole SAFETY-25 had to
|
||||
close in `shaping_suspended()`, where a suspension gated on the forecast
|
||||
alone could not fire on the very site that needed it. This number comes off
|
||||
`decide()`, which runs wherever P1 does.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
WHERE THE NUMBER COMES FROM: IT IS `wanted_w`, READ IN THE OTHER DIRECTION
|
||||
|
||||
`decide()` already computes
|
||||
|
||||
wanted = batt_w + excess = (the offtake there would be with the battery
|
||||
at zero) - (the level this quarter can still afford)
|
||||
|
||||
as the battery DISCHARGE that would land the quarter exactly on the ceiling.
|
||||
A negative `wanted` is not "nothing to say" - it is a permitted CHARGE of
|
||||
`-wanted` watts, and throwing it away is SAFETY-45's whole defect. So this
|
||||
function invents no arithmetic; it reads the sign the guard already had.
|
||||
|
||||
⚠️ AND THE QUANTITY IS INVARIANT IN THE BATTERY, WHICH IS WHY SIZING A TRADE
|
||||
TO IT CANNOT OSCILLATE. Raise the charge by dW and the meter rises by dW, so
|
||||
`excess` rises by exactly dW while `batt_w` falls by dW: `wanted` does not
|
||||
move. It is a FEED-FORWARD number - a function of the house, the ceiling and
|
||||
the seconds already banked - so consuming it adds no feedback path around the
|
||||
plant. The fixed point is `charge = ceiling - load`, with the meter sitting
|
||||
ON the ceiling and `wanted` parked at `load - ceiling`, a whole `ceiling -
|
||||
load` clear of the engagement boundary rather than chattering across it.
|
||||
|
||||
⚠️ AND A QUARTER BOUNDARY DOES NOT HAND IT BACK AT FULL POWER, WHICH IS THE
|
||||
OTHER HALF OF SAFETY-45 AND IS NOT THE SAME CLAIM AS "IT DOES NOT CHANGE".
|
||||
It DOES change - it is `(900 / remaining) * (ceiling - projected)`, so it is
|
||||
largest in the last seconds of a block and collapses at the boundary. What
|
||||
matters is WHAT IT COLLAPSES TO: at `elapsed = 0` the projection IS the held
|
||||
level, so the answer is `ceiling - (load - pv)` - the house and the cap, and
|
||||
nothing else. A trade refused at 14:59 therefore resumes at 15:00 at the rate
|
||||
the new quarter can afford, not at `max_w`, and §10.1's answer survives the
|
||||
boundary because the arithmetic does: no timer, no backoff constant, no state
|
||||
carried between calls.
|
||||
|
||||
⚠️ AND THE AMPLIFICATION IS BOUNDED IN ITS EFFECT, NOT MERELY LARGE. Hold a
|
||||
charge of exactly this size for the rest of the block and the block's average
|
||||
lands on `ceiling` EXACTLY, wherever in the block it started:
|
||||
|
||||
(acc + (held + headroom) * remaining) / 900
|
||||
= projected + (900/remaining) * (ceiling - projected) * remaining/900
|
||||
= ceiling
|
||||
|
||||
so 162 kW of headroom with 5 s left and 900 W of it with the whole quarter to
|
||||
go are the same statement about the bill. `test_peakguard.py` part 13 sweeps
|
||||
that identity across the block rather than arguing it here.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
THE THREE ANSWERS
|
||||
|
||||
`None` nothing measured it: the guard never ran (`meter_source: off`), or
|
||||
it ran with no battery reading to size a floor from, or the block
|
||||
had no seconds left to influence. ⚠️ None IS NOT UNLIMITED. A caller
|
||||
that treats it as "charge away" is `arbitrage.guard_state()`'s
|
||||
collapse of None into False, one layer down - a strategy creating
|
||||
the billed quantity while nothing measures the quarter it lands in.
|
||||
`0.0` measured, and the answer is no charging: the guard is BLIND (its
|
||||
claim already says so at `floor 0 W` and this agrees with it rather
|
||||
than restating it), or it is holding and `wanted >= 0`.
|
||||
`> 0` the watts a charge may pull this cycle.
|
||||
|
||||
⚠️ HOLDING IMPLIES ZERO, BY CONSTRUCTION AND NOT BY COINCIDENCE. Every state
|
||||
that files a claim with `engaged=True` has `wanted > 0`, `wanted is None` or
|
||||
`blind`, so this answers 0.0 or None there and can never hand a strategy
|
||||
permission the guard's own `lo` is at that instant refusing.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
⚠️ WHY THIS IS A SIZING AND NOT A CLAIM, AND DO NOT "SIMPLIFY" IT INTO ONE
|
||||
|
||||
The obvious tidier answer is to delete `decide()`'s `wanted <= 0` gate and
|
||||
let it file `lo = wanted` unconditionally - a NEGATIVE floor, meaning "you
|
||||
may charge, but no harder than this". The arithmetic is identical, it is
|
||||
continuous, and it would bind every claimant rather than only arbitrage. It
|
||||
was measured, considered and REJECTED, and the reason is not style:
|
||||
|
||||
* `main.py`'s cheap-window maintenance charge files
|
||||
`Claim.limit("maintenance", P_MAINT_SHAPE, hi=-floor)` - a NEGATIVE `hi`.
|
||||
arbiter.py clause 2 applies EVERY limit at or above the winner's priority
|
||||
and takes the most restrictive, with no notion of one limit out-ranking
|
||||
another. A peak `lo = -300 W` against a shaping `hi = -1000 W` is
|
||||
`lo > hi`: a CONTRADICTION, which resolves to 0 W - the battery PARKED,
|
||||
in the one quarter of the month that sets the bill. That is the exact
|
||||
failure `shaping_suspended()` exists to prevent, and the only way to
|
||||
close it would be to key that suppression on "a claim exists", which on
|
||||
every site this card is about suspends the maintenance charge-only
|
||||
shaping PERMANENTLY.
|
||||
* and it would change what `engaged` MEANS at five call sites outside this
|
||||
module - `arbitrage.guard_state()`, `shaping_suspended()`, `claim()`,
|
||||
main.py's edge-logged action line and main.py's status row - each of
|
||||
which today reads it as "the guard is HOLDING".
|
||||
|
||||
`control.maintenance_charge_floor()` is a sizing and not a limit for the same
|
||||
reason, which is why this is the shape that already fits.
|
||||
DECISIONS/SAFETY-45-sizing-the-trade.md §2b carries the full argument.
|
||||
"""
|
||||
if decision is None:
|
||||
return None
|
||||
if decision.blind:
|
||||
return 0.0
|
||||
if decision.wanted_w is None:
|
||||
return None
|
||||
return max(0.0, -float(decision.wanted_w))
|
||||
|
||||
|
||||
def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
|
||||
"""Must the maintenance charge-only shaping stand down this cycle?
|
||||
|
||||
|
||||
@@ -0,0 +1,361 @@
|
||||
"""SAFETY-10 - shadow mode: the whole decision path, and no command.
|
||||
|
||||
WHAT DEFECT THIS PREVENTS
|
||||
=========================
|
||||
Not one defect - the CLASS of them. Every optimiser fault this repository has
|
||||
found was invisible from outside while it was happening, and each one was paid
|
||||
for at the meter before anybody could see it:
|
||||
|
||||
* SAFETY-45 arbitrage against a binding `peak_cap_w` ran 28 charge onsets an
|
||||
hour, the grid swinging -455 .. +3200 W, and put a billed
|
||||
quarter 59 W over the cap;
|
||||
* TARIFF-14 the price lookup answered for the wrong quarter-hour 45 minutes
|
||||
in every 60, and traded on it;
|
||||
* SAFETY-46 the SoC ceiling churns 598 Wh to gain 310 Wh, no hysteresis.
|
||||
|
||||
There was no way to WATCH what the optimiser would do without letting it do it.
|
||||
A commissioning engineer could arm arbitrage and find out, or not arm it and
|
||||
learn nothing. Shadow mode is the third option: strategies, arbiter, clamps and
|
||||
guards all run, the decision is recorded with its reason, and NOTHING THE
|
||||
CONTROLLER DECIDES REACHES THE INVERTER.
|
||||
|
||||
⚠️ "REACHES NOTHING" IS NOT "WRITES NOTHING", AND THE DIFFERENCE IS THE WHOLE
|
||||
SAFETY ARGUMENT
|
||||
=======================================================================
|
||||
The inverter holds its last command FOREVER - it has no meter timeout
|
||||
(HANDOVER.md §6), and firmware/goodwe-master.yaml's header records what that
|
||||
cost when a controller stopped refreshing: Illusmart went silent mid-command
|
||||
and the inverter held +5000 W for 113 s. main.py's own header carries the same
|
||||
measurement. So a shadow mode that
|
||||
simply stopped writing would leave whatever was standing when it was switched
|
||||
on standing for as long as it was left on. That is the exact failure this
|
||||
repository keeps finding - LOOKS HEALTHY BUT IS INERT - with the status page
|
||||
calmly reporting that nothing is being commanded.
|
||||
|
||||
So shadow mode does write, and it writes ONE number:
|
||||
|
||||
the actuator is held at WIRE_W (0.0 W), refreshed on the ordinary
|
||||
heartbeat, by the ordinary single writer.
|
||||
|
||||
That is a DEFINED, SAFE actuator state, it is the same state the operator's
|
||||
stop button reaches, and it honours the contract firmware/goodwe-master.yaml
|
||||
§"CONTRACT CHANGE" imposes on us - HA must rewrite the setpoint every ~10 s or
|
||||
the ESP32's 30 s stale-input watchdog cannot tell "steady" from "dead". Going
|
||||
silent would put that board into a tripped-watchdog state for the whole shadow
|
||||
run, which is an ALARM being used as a MODE: the operator who learns that
|
||||
`wd_tripped` is normal during shadow runs is the operator who ignores it when
|
||||
the add-on has actually died.
|
||||
|
||||
⚠️ AND IT IS NOT A SECOND WRITE PATH. SAFETY-28's rule is one actuator, one
|
||||
writer. Shadow mode files no claim, owns no transport and calls nothing in
|
||||
hass.py. It is a SUBSTITUTION inside `Controller._write_unit()` - the single
|
||||
choke point every write in this add-on already goes through - in exactly the
|
||||
form the three substitutions above it take (non-finite -> 0 W, unauthorised ->
|
||||
0 W, clamped -> the rating). It is the LAST of them, so SAFETY-28's
|
||||
authorisation gate and SAFETY-03's clamp still grade the number the decision
|
||||
path actually produced, and a shadow run therefore records that the clamp WOULD
|
||||
have engaged.
|
||||
|
||||
THE DEFAULT, AND WHY IT IS NOT A PLAIN `true` (§ the ticket's own warning)
|
||||
==========================================================================
|
||||
The card is titled "default-on". Taken literally - `shadow_mode: true` in
|
||||
`config.yaml`'s `options:` block - it is the worst change in this repository's
|
||||
history. Home Assistant's Supervisor composes an add-on's effective options as
|
||||
`{**config.yaml defaults, **the stored user options}`, so a NEW key with a new
|
||||
default reaches EVERY install on the next update, including the one regulating
|
||||
a real battery in the author's house today. Literal default-on silently stops
|
||||
an existing install from controlling, and the only symptom is a battery that
|
||||
has stopped doing anything.
|
||||
|
||||
There is no mechanism in the add-on options system that lets one key default
|
||||
differently for a new install and an existing one: `options:` IS the default,
|
||||
and there is exactly one of it. So "default-on for new" has to be expressed as
|
||||
a value the add-on RESOLVES, not as a constant the Supervisor merges.
|
||||
|
||||
Hence three values rather than two, defaulting to `auto`:
|
||||
|
||||
off never shadow. The controller commands the battery.
|
||||
on always shadow, whatever the start/stop button says.
|
||||
auto shadow WHILE CONTROL IS STOPPED; live once it is started.
|
||||
|
||||
`auto` is default-on for a new install and a no-op for an existing one, and it
|
||||
is that without any persisted marker, any migration, and any guess:
|
||||
|
||||
* a FRESH install ships `auto_start: false` and has no stored `auto` key, so
|
||||
it comes up stopped -> shadow. It observes a day of decisions before it is
|
||||
ever allowed to command anything. That is the card's intent, delivered.
|
||||
* an install that is CONTROLLING - `auto_start: true`, or the operator has
|
||||
pressed *Start / stop control* and the store carries `auto: true` - is
|
||||
started, so `auto` resolves to LIVE and its behaviour does not change by
|
||||
one watt.
|
||||
* an install that is STOPPED keeps its actuator at 0 W exactly as before -
|
||||
the same number, from the same writer, on the same heartbeat - and gains
|
||||
the recording. The only thing that changes for it is what the status page
|
||||
and the action log SAY.
|
||||
|
||||
⚠️ AND `auto` MEANS THE START BUTTON LEAVES SHADOW MODE. That is deliberate:
|
||||
under `auto` the button reads "Start / stop control" and pressing Start is the
|
||||
operator saying "control the battery". An operator who wants the decisions
|
||||
recorded WHILE the loop runs sets `shadow_mode: on` explicitly - that is the
|
||||
configuration this card exists to make possible, and it is the one that cannot
|
||||
be reached by accident.
|
||||
|
||||
⚠️ AN UNRECOGNISED VALUE RESOLVES TO SHADOW, NOT TO LIVE. `validate.py` refuses
|
||||
it at startup so this is not meant to be reachable, but the fail-safe direction
|
||||
for "the operator's intent is unreadable" is the one that does not move energy.
|
||||
|
||||
THE FAILSAFES, ONE BY ONE (the card asks for each to be decided and recorded)
|
||||
============================================================================
|
||||
| failsafe | in shadow mode |
|
||||
|--------------------------------|-------------------------------------------|
|
||||
| SAFETY-02/30 sign watchdogs | INERT, and by construction rather than by |
|
||||
| (per-unit and site) | a special case. They grade |
|
||||
| | `Inverter.standing_w()` - what this |
|
||||
| | controller has standing on the wire - and |
|
||||
| | shadow mode holds that at 0 W. A 0 W |
|
||||
| | command cannot oppose a meter, so the |
|
||||
| | detector never arms. ⚠️ THIS IS THE ONE |
|
||||
| | THAT HAD TO BE GOT RIGHT: fed the SHADOW |
|
||||
| | decision instead, every shadow run would |
|
||||
| | latch a trip within `sign_disagree_s` - |
|
||||
| | the decision opposes a meter that never |
|
||||
| | saw it - and that latch SURVIVES INTO |
|
||||
| | LIVE OPERATION and a restart. Shadow mode |
|
||||
| | would manufacture the failsafe it is |
|
||||
| | meant to help debug. |
|
||||
| SAFETY-03 clamp | OBSERVES. It runs on the number the |
|
||||
| | decision path produced, `clamp_last` is |
|
||||
| | set and every engagement goes to the |
|
||||
| | action log, because "it would have hit |
|
||||
| | the rating" is part of what a shadow run |
|
||||
| | is for. It changes no command: the value |
|
||||
| | it narrows is replaced by 0 W below it. |
|
||||
| SAFETY-28 write authorisation | OBSERVES, for the same reason and in the |
|
||||
| | same place - above the substitution, so |
|
||||
| | it still asks who chose the number. |
|
||||
| SAFETY-18 meter freeze | OBSERVES, unchanged. It takes no action |
|
||||
| | in live operation either; it grades the |
|
||||
| | resolved intent against a meter that has |
|
||||
| | stopped moving, and both halves are as |
|
||||
| | true in shadow as out of it. |
|
||||
| SAFETY-07/24/25 peak guard | OBSERVES. Level-triggered, unlatched, and |
|
||||
| | it files its claim as usual so the |
|
||||
| | recorded decision is the real one. |
|
||||
| | SAFETY-45's limit cycle is visible from a |
|
||||
| | shadow run; that is the point. |
|
||||
| SAFETY-31 circulation | OBSERVES AND MAY LATCH, legitimately. Its |
|
||||
| SAFETY-42 delivery | evidence is MEASURED power, not a |
|
||||
| | command: packs pushing against each other |
|
||||
| | while every one of them is told 0 W is a |
|
||||
| | real fault and a latch is the right |
|
||||
| | answer to it. |
|
||||
| operator stop (`auto` False) | SUPPRESSED AS A CLAIM, ENFORCED AT THE |
|
||||
| | WIRE. It is the one deliberate change. |
|
||||
| | Its `P_SAFETY` 0 W claim out-ranks |
|
||||
| | everything, so leaving it in would make |
|
||||
| | the recorded decision "stopped" on every |
|
||||
| | cycle - the shadow run would answer the |
|
||||
| | wrong question. The actuator state is |
|
||||
| | identical either way, and the wire |
|
||||
| | substitution is STRICTLY STRONGER than |
|
||||
| | the claim: a claim can be out-ranked, and |
|
||||
| | this cannot. |
|
||||
| inputs missing, non-finite, | UNCHANGED. All of them resolve to 0 W, |
|
||||
| allocator refusal, arbiter | which is what the wire gets in shadow |
|
||||
| contradiction | mode anyway, so they act redundantly and |
|
||||
| | are recorded as they always were. |
|
||||
|
||||
⚠️ MAINTENANCE IS NOT IN THAT TABLE BECAUSE SHADOW MODE DOES NOT TOUCH IT. The
|
||||
state machines are ticked on every cycle today whether control is started or
|
||||
not, so a stopped install already runs them against a battery that does not
|
||||
move. Shadow mode inherits that, unchanged and unimproved; it is a pre-existing
|
||||
property of `auto_start: false` and it is recorded here rather than quietly
|
||||
fixed under another card's name.
|
||||
|
||||
LEAVING SHADOW MODE
|
||||
===================
|
||||
`Controller.cycle()` re-seeds its carried command (`self.target` and each
|
||||
`inv.target`) to WIRE_W at the END of every shadow cycle, AFTER every in-cycle
|
||||
guard has read the decision. Two things follow, and both are safety properties:
|
||||
|
||||
* the loop's `prev_w` and its integrator track WHAT IS ACTUALLY STANDING ON
|
||||
THE WIRE, so every shadow cycle answers "from where the plant really is,
|
||||
what would this controller do NOW" - a true statement about the present,
|
||||
rather than a simulation of a counterfactual plant that drifts further from
|
||||
reality every tick;
|
||||
* the exit is safe BY CONSTRUCTION. The carried command already equals the
|
||||
standing command, so the first live cycle slews from 0 W like any other
|
||||
cycle. Carrying the shadow decision instead would let the slew limiter
|
||||
depart from a base that never existed - up to a full `slew_w` step onto a
|
||||
battery sitting at zero.
|
||||
|
||||
The entry is safe for the ordinary reason: the substitution happens on the very
|
||||
first write of the very first shadow cycle, and `last_write` was not 0 W, so
|
||||
that write is issued rather than skipped as unchanged.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
# ⚠️ CFG-03's mirror. `test_defaults_pin.py` part 2 discovers every
|
||||
# module-level name ending in OPTION_DEFAULTS and asserts each value
|
||||
# reproduces config.yaml EXACTLY, so this table cannot drift from the shipped
|
||||
# default. Nothing in the add-on may carry a literal fallback for a key a
|
||||
# mirror answers for - part 3 scans for that - which is why `main.py` asks the
|
||||
# functions below and never reads `shadow_mode` itself.
|
||||
SHADOW_OPTION_DEFAULTS = {
|
||||
"shadow_mode": "auto",
|
||||
}
|
||||
|
||||
#: The three values `shadow_mode` may take, in the order config.yaml's schema
|
||||
#: lists them. `validate.py` refuses anything else by name.
|
||||
MODES = ("auto", "on", "off")
|
||||
|
||||
#: What stands on the wire while shadow mode is engaged. ⚠️ A NUMBER, NOT A
|
||||
#: SILENCE - see this module's header. It is 0.0 W for the same reason every
|
||||
#: other refusal in this add-on is 0.0 W: fail toward inaction, and keep
|
||||
#: commanding it so the inverter cannot be left latched on anything else.
|
||||
WIRE_W = 0.0
|
||||
|
||||
|
||||
def mode(opts: dict) -> str:
|
||||
"""The configured `shadow_mode`, normalised to one of `MODES`.
|
||||
|
||||
⚠️ AN UNRECOGNISED VALUE ANSWERS `"on"`, NOT `"auto"` AND NOT `"off"`.
|
||||
`validate.py` refuses such a value at startup, so this branch is not meant
|
||||
to be reachable at all; it exists because the fail-safe direction for "the
|
||||
operator's intent cannot be read" is the one that does not move energy. A
|
||||
typo that silently resolved to `off` would put a battery under a controller
|
||||
whose configuration nobody could parse.
|
||||
"""
|
||||
raw = opts.get("shadow_mode", SHADOW_OPTION_DEFAULTS["shadow_mode"])
|
||||
text = str("" if raw is None else raw).strip().lower()
|
||||
if text in MODES:
|
||||
return text
|
||||
return "on"
|
||||
|
||||
|
||||
def engaged(opts: dict, *, control_started: bool) -> bool:
|
||||
"""Is the battery being left alone right now?
|
||||
|
||||
`control_started` is `Controller.auto` - the persisted start/stop state,
|
||||
which a fresh install gets from `auto_start` and an operator moves with the
|
||||
*Start / stop control* button. See the header on why `auto` reads it.
|
||||
"""
|
||||
m = mode(opts)
|
||||
if m == "off":
|
||||
return False
|
||||
if m == "on":
|
||||
return True
|
||||
return not control_started
|
||||
|
||||
|
||||
def why(opts: dict, *, control_started: bool) -> str:
|
||||
"""Which rung decided, in the words an operator can act on.
|
||||
|
||||
⚠️ THE REASON, NOT ONLY THE VERDICT - MUTATION.md's masking rule. `on` and
|
||||
`auto`-while-stopped produce the same boolean and want different operator
|
||||
actions: one is turned off by editing an option, the other by pressing a
|
||||
button. A surface that showed only "shadow" would make a mutation that
|
||||
swapped the two rungs invisible.
|
||||
"""
|
||||
# ⚠️ THE LIVE SENTENCES SAY "NOT IN SHADOW MODE", NOT "THE BATTERY IS
|
||||
# BEING CONTROLLED". The second is FALSE on a stopped install with
|
||||
# `shadow_mode: off` - nothing is regulating there either - and a row that
|
||||
# is false in one of the four live states is a row an operator learns to
|
||||
# discount. What is true in every live state is that what this add-on
|
||||
# decides reaches the inverter; whether control is RUNNING is the
|
||||
# `Stopped` banner's question and it is answered there.
|
||||
m = mode(opts)
|
||||
if m == "off":
|
||||
return ("off (shadow_mode: off) - NOT in shadow mode: what this "
|
||||
"add-on decides DOES reach the inverter")
|
||||
if m == "on":
|
||||
return ("on (shadow_mode: on) - decisions are recorded and nothing "
|
||||
"is commanded")
|
||||
if control_started:
|
||||
return ("off (shadow_mode: auto, control is started) - NOT in shadow "
|
||||
"mode: what this add-on decides DOES reach the inverter")
|
||||
return ("on (shadow_mode: auto, control is stopped) - decisions are "
|
||||
"recorded and nothing is commanded")
|
||||
|
||||
|
||||
def words(opts: dict, *, control_started: bool, would_w: float | None,
|
||||
reason: str = "") -> str:
|
||||
"""The status page's `Shadow mode` row.
|
||||
|
||||
⚠️ THE ROW IS RENDERED IN EVERY STATE, INCLUDING `off`. A surface whose
|
||||
ABSENCE is how you learn which mode you are in is a surface an operator
|
||||
has to already know about; TARIFF-11's rule is that the rendered text is
|
||||
what gets graded, so there has to be text in both states.
|
||||
|
||||
`would_w` is the decision the path reached this cycle - what a live
|
||||
controller would have put on the wire - and `reason` is
|
||||
`Resolution.explain()`, the same sentence the `Why` row carries. Together
|
||||
they are the whole of "what would it have done, and why"; without them the
|
||||
row would say a shadow run happened and nothing about what it found.
|
||||
"""
|
||||
head = why(opts, control_started=control_started)
|
||||
if not engaged(opts, control_started=control_started):
|
||||
return head
|
||||
if would_w is None:
|
||||
return (f"{head}; no decision has been reached yet - the inverter is "
|
||||
f"held at {WIRE_W:.0f} W")
|
||||
# ⚠️ THE THOUSANDS SEPARATOR IS SWAPPED ON THE NUMBER ALONE. Applied to
|
||||
# the whole sentence it ate the comma out of `head` - and `head` is the
|
||||
# half that says WHICH RUNG decided, which is the claim MUTATION.md's
|
||||
# masking rule says must survive.
|
||||
num = f"{float(would_w):+,.0f}".replace(",", " ")
|
||||
out = (f"{head}; WOULD HAVE COMMANDED {num} W, inverter held at "
|
||||
f"{WIRE_W:.0f} W")
|
||||
if reason:
|
||||
out += f" - {reason}"
|
||||
return out
|
||||
|
||||
|
||||
def banner(opts: dict, *, control_started: bool, latched: tuple = ()) -> tuple:
|
||||
"""`(level, text)` for the top of the status page, or `None` when live.
|
||||
|
||||
⚠️ IT NAMES A STANDING LATCH AND GOES RED FOR ONE. The shadow banner sits
|
||||
ABOVE every other branch of the cascade, because "the battery is not being
|
||||
controlled" is the one sentence that may never be displaced - but a
|
||||
failsafe latch that is up while the controller is inert is up when it
|
||||
stops being inert, and an operator who turns shadow mode off without
|
||||
clearing it gets a battery that will not move and a green page that
|
||||
never mentioned why. So the latch is carried INTO the shadow banner
|
||||
rather than losing its own.
|
||||
"""
|
||||
if not engaged(opts, control_started=control_started):
|
||||
return None
|
||||
text = ("SHADOW MODE - the battery is NOT being controlled. Every "
|
||||
f"inverter is held at {WIRE_W:.0f} W and nothing this add-on "
|
||||
"decides reaches the inverter.")
|
||||
if latched:
|
||||
return ("bad", text + " ⚠️ A FAILSAFE LATCH IS STILL UP ("
|
||||
+ ", ".join(latched) + ") and it will still be up when shadow "
|
||||
"mode is turned off.")
|
||||
return ("warn", text)
|
||||
|
||||
|
||||
def problems(opts: dict) -> list:
|
||||
"""`validate.py`'s rule: `shadow_mode` must be one of the three values.
|
||||
|
||||
⚠️ THE SENTENCE SPELLS `shadow_mode`. `configui.problems_by_field()` files
|
||||
a refusal under the field whose key its text contains; a rule that never
|
||||
names a key lands in the page's top-level block instead, where the operator
|
||||
cannot see which control is wrong. UX-02's whole point is that the shipped
|
||||
validator is the only rule surface, so the rule has to be readable there.
|
||||
|
||||
⚠️ AND IT IS A REFUSAL RATHER THAN A COERCION. `mode()` resolves an
|
||||
unreadable value to shadow, which is the safe direction but is also a
|
||||
SILENT reinterpretation of what the operator wrote - and an install left in
|
||||
shadow mode by a typo commands nothing at all, indefinitely.
|
||||
"""
|
||||
raw = opts.get("shadow_mode", SHADOW_OPTION_DEFAULTS["shadow_mode"])
|
||||
text = str("" if raw is None else raw).strip().lower()
|
||||
if text in MODES:
|
||||
return []
|
||||
return [f"shadow_mode is {raw!r}, which is not one of "
|
||||
+ ", ".join(f"'{m}'" for m in MODES)
|
||||
+ ". 'auto' leaves the battery alone while control is stopped and "
|
||||
"commands it once control is started; 'on' records every "
|
||||
"decision and commands nothing at all; 'off' is ordinary "
|
||||
"control."]
|
||||
@@ -334,6 +334,7 @@ from .peakguard import PEAK_OPTION_DEFAULTS
|
||||
from .price import (
|
||||
PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS,
|
||||
SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
|
||||
from .shadow import problems as shadow_problems
|
||||
from .static_tariff import (
|
||||
ProfileInvalid, TAXES_PROFILE_OPTION, parse_static_profile,
|
||||
parse_taxes_profile)
|
||||
@@ -840,6 +841,18 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
|
||||
# missing rating one line up.
|
||||
problems.extend(_roster_problems(opts))
|
||||
|
||||
# --- 11. SAFETY-10's shadow mode, and it is a REFUSAL ---------------------
|
||||
# `shadow_mode` decides whether this controller commands the battery at all,
|
||||
# so an unreadable value is not a detail to log and carry on past.
|
||||
# `shadow.mode()` resolves an unrecognised one to SHADOW - the direction
|
||||
# that does not move energy - and an install silently reinterpreted that way
|
||||
# commands nothing, indefinitely, while its status page calmly explains
|
||||
# that this is intentional. UX-02 made this validator the ONE rule surface
|
||||
# both editors read, so the refusal belongs here rather than in a coercion
|
||||
# nobody can see. The sentence spells `shadow_mode` so
|
||||
# `configui.problems_by_field()` can file it under the field.
|
||||
problems.extend(shadow_problems(opts))
|
||||
|
||||
# --- 2. the configured ceiling against the device's own rating -----------
|
||||
# ⚠️ THE FLAT `max_w`, AND ONLY THE FLAT ONE. `dev_min`/`dev_max` are ONE
|
||||
# device's range - the flat `setpoint_entity`'s - so this rule can only ever
|
||||
|
||||
@@ -746,6 +746,38 @@ options:
|
||||
# and not 150 or 200. 37 control cycles.
|
||||
delivery_hold_s: 185
|
||||
|
||||
# SAFETY-10. Run the whole decision path and command NOTHING - strategies,
|
||||
# arbiter, clamps and guards all run, the decision and its reason are
|
||||
# recorded, and every inverter is held at 0 W. `app/shadow.py` carries the
|
||||
# argument; the three things to know before changing this line are:
|
||||
#
|
||||
# auto shadow WHILE CONTROL IS STOPPED, live once it is started. This is
|
||||
# the shipped value and it is what "default-on" means here.
|
||||
# on always shadow, whatever the Start / stop button says. This is the
|
||||
# one an operator picks to watch a day of decisions on an armed site
|
||||
# before letting it trade.
|
||||
# off ordinary control.
|
||||
#
|
||||
# ⚠️ IT IS NOT A BOOLEAN DEFAULTING TO `true`, AND THAT IS THE WHOLE CARD.
|
||||
# The Supervisor composes an add-on's options as `{**these defaults, **the
|
||||
# stored user options}`, so a NEW key with a new default reaches every
|
||||
# EXISTING install on the next update - including one regulating a real
|
||||
# battery. `shadow_mode: true` would silently stop it, and the only symptom
|
||||
# would be a battery that has stopped doing anything. There is no mechanism
|
||||
# in this options system that lets one key default differently for a new
|
||||
# install and an existing one, so "default-on for new" has to be a value the
|
||||
# add-on RESOLVES. `auto` is that value: a fresh install ships
|
||||
# `auto_start: false` and therefore comes up in shadow mode; an install that
|
||||
# is controlling is started, so `auto` resolves to live and NOTHING about it
|
||||
# changes.
|
||||
#
|
||||
# ⚠️ AND UNDER `auto` THE START BUTTON LEAVES SHADOW MODE. Pressing *Start /
|
||||
# stop control* is the operator saying "control the battery". Somebody who
|
||||
# wants the decisions recorded WHILE the loop runs sets `on` explicitly -
|
||||
# which is the configuration this option exists for, and the one that cannot
|
||||
# be reached by accident.
|
||||
shadow_mode: "auto"
|
||||
|
||||
# ==========================================================================
|
||||
# ADVANCED - the control law and diagnostics
|
||||
# ==========================================================================
|
||||
@@ -1065,6 +1097,15 @@ schema:
|
||||
# running short of one unit's share must be reported well inside one.
|
||||
delivery_hold_s: int(30,900)
|
||||
|
||||
# SAFETY-10. ⚠️ A THREE-VALUED LIST AND NOT A `bool`, for the reason written
|
||||
# against the default in the options block above: a boolean has one default
|
||||
# and the Supervisor gives it to every install, new and existing alike.
|
||||
# `app/shadow.MODES` is this tuple and `validate.py` rule 11 refuses anything
|
||||
# else BY NAME, because `shadow.mode()` resolves an unreadable value to
|
||||
# SHADOW - safe, but a silent reinterpretation that commands nothing for as
|
||||
# long as nobody notices.
|
||||
shadow_mode: list(auto|on|off)
|
||||
|
||||
# ==========================================================================
|
||||
# ADVANCED - the control law and diagnostics
|
||||
# ==========================================================================
|
||||
|
||||
@@ -73,6 +73,7 @@ Read MUTATION.md before you report a survivor.
|
||||
|
||||
import ast
|
||||
import inspect
|
||||
import math
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime, timedelta, timezone
|
||||
@@ -84,6 +85,11 @@ from app.arbiter import (
|
||||
P_ARBITRAGE, P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_PEAK, P_SAFETY, Claim,
|
||||
resolve,
|
||||
)
|
||||
# SAFETY-45 section 3c. The shipped loop, the shipped billed-quarter
|
||||
# accumulator and the shipped projection - nothing here is transcribed.
|
||||
from app.control import Tuning, compute
|
||||
from app.p1 import QUARTER_S, QuarterAverager, make_sample, split_signed
|
||||
from app.tariff import PeakTracker
|
||||
from app.arbitrage import (
|
||||
CHARGE, DISCHARGE, ArbitrageDecision, claim, decide, enabled, soc_bounds,
|
||||
threshold_eur_kwh,
|
||||
@@ -203,10 +209,19 @@ def hour(i, *, start=D0):
|
||||
return start + timedelta(hours=i, minutes=30)
|
||||
|
||||
|
||||
# SAFETY-45. THE HEADROOM EVERY CHECK THAT IS NOT ABOUT THE HEADROOM USES, and
|
||||
# it is deliberately NOT binding: `min(MAX_W, this)` is MAX_W, so every existing
|
||||
# check in this file grades what it always graded and the new rung is decoration
|
||||
# in all of them. Section 3b is where it is made to bind, and 3b asserts the
|
||||
# precondition that it does (MUTATION.md habit 1) rather than hoping.
|
||||
HEADROOM_CLEAR = MAX_W * 10.0
|
||||
|
||||
|
||||
def act(plan, i, *, peak=False, soc=50.0, thresh=0.0, unc=frozenset(),
|
||||
floor=20.0, ceiling=95.0, start=D0):
|
||||
floor=20.0, ceiling=95.0, start=D0, headroom=HEADROOM_CLEAR):
|
||||
"""`decide()` with the fixture's constants filled in. One call shape."""
|
||||
return decide(plan, hour(i, start=start), peak_guard_active=peak, soc=soc,
|
||||
charge_headroom_w=headroom,
|
||||
min_spread_eur_kwh=thresh, uncertainty=unc,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=floor, soc_ceiling_pct=ceiling)
|
||||
@@ -721,6 +736,7 @@ check("a peak floor does NOT cap an arbitrage DISCHARGE - §9.1 bills offtake "
|
||||
# MECHANISM 3, which is neither of the above: the guard that never ran.
|
||||
_blind = decide(PLAN, hour(CHEAP_H), peak_guard_active=None, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=20.0, soc_ceiling_pct=95.0)
|
||||
check("a peak guard that NEVER RAN is a third state, and it refuses: `None` is "
|
||||
@@ -750,6 +766,323 @@ check("...and cycle() calls it rather than inlining the conjunction, so a "
|
||||
encoding="utf-8").read(), "cycle")))
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
print()
|
||||
print("3b. SAFETY-45 - the buy leg is SIZED by the guard, not switched by it")
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC3 above is the SWITCH: `peak_guard_active` refuses the whole trade while
|
||||
# the guard holds. That is right and it stays. What was missing is the other
|
||||
# half - the guard measures a CONTINUOUS number, "the watts this billed quarter
|
||||
# can still afford", and until this card nothing consumed it. So a trade sat at
|
||||
# max_w through the whole window in which the guard was silent, blew the
|
||||
# quarter, tripped the switch, was cancelled outright, and came back at max_w
|
||||
# the moment the meter fell far enough to release it. Measured on TEST-23
|
||||
# stage 3's closed rig at peak_cap_w 1500 / max_w 2000 / a 1200 W house:
|
||||
# 28 charge onsets in one hour, mean period 131 s, grid -456 <-> +3200 W.
|
||||
#
|
||||
# `control.maintenance_charge_floor()` has always given a MAINTENANCE charge
|
||||
# exactly this shape - "capped by the headroom left under the site's cap" - and
|
||||
# its own docstring says why: "a maintenance charge is the only thing this
|
||||
# system does that is big enough and long enough to set that peak". OPT-04 is
|
||||
# the second such thing and was given no cap. This section grades the cap.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# ⚠️ THE PRECONDITION, AND IT IS THE HABIT-1 ONE. The headroom must be strictly
|
||||
# between 0 and the size the trade would otherwise ask for, or "sized by the
|
||||
# guard" is indistinguishable from "not sized at all" and from "refused".
|
||||
S45_HEADROOM = 300.0
|
||||
check(f"PRECONDITION: the headroom under test ({S45_HEADROOM:.0f} W) is "
|
||||
f"strictly inside the trade's own sizing ({MAX_W:.0f} W) and strictly "
|
||||
f"positive, so a cap that did nothing and a cap that refused everything "
|
||||
f"are both distinguishable from the answer below",
|
||||
0.0 < S45_HEADROOM < MAX_W)
|
||||
_s45_capped = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER,
|
||||
headroom=S45_HEADROOM)
|
||||
_s45_clear = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER)
|
||||
print(f" headroom {S45_HEADROOM:.0f} W -> {_s45_capped.power_w:+.0f} W; "
|
||||
f"headroom clear -> {_s45_clear.power_w:+.0f} W")
|
||||
print(f" {_s45_capped.reason}")
|
||||
check("the trade still HAPPENS - §10.1 ranks peak shaving above arbitrage, it "
|
||||
"does not abolish it - and it is sized to the watts the billed quarter "
|
||||
"can afford rather than to max_w",
|
||||
_s45_capped.action == CHARGE
|
||||
and near(_s45_capped.power_w, -S45_HEADROOM))
|
||||
check("...and the claim the arbiter receives carries the SIZED number, so the "
|
||||
"cap reaches the actuator and is not merely printed",
|
||||
near(claim(_s45_capped).value, -S45_HEADROOM)
|
||||
and claim(_s45_capped).priority == P_ARBITRAGE)
|
||||
check("...and the SAME call with the headroom clear asks for max_w, so the "
|
||||
"check above is graded against a difference this fixture can actually "
|
||||
"produce (habit 7: one thing varied, from an accepted baseline)",
|
||||
_s45_clear.action == CHARGE and near(_s45_clear.power_w, -MAX_W))
|
||||
|
||||
# ⚠️ THE ORDERED PAIR (MUTATION.md habit 14). Two numbers in one sentence can
|
||||
# always be transposed by a ZERO-BYTE edit, and this sentence is what an
|
||||
# operator reads when the battery buys less than the price says it should. So
|
||||
# the check asserts each value inside the literal text that names it, and
|
||||
# asserts that the TRANSPOSED sentence is not what it says.
|
||||
_S45_PAIR = (f"the trade asked for {MAX_W:.0f} W and this billed quarter can "
|
||||
f"afford {S45_HEADROOM:.0f} W")
|
||||
_S45_SWAP = (f"the trade asked for {S45_HEADROOM:.0f} W and this billed "
|
||||
f"quarter can afford {MAX_W:.0f} W")
|
||||
check("the reason names WHAT WAS ASKED FOR and WHAT WAS AFFORDABLE in their "
|
||||
"own slots, so an operator can tell a small trade from a small "
|
||||
"opportunity", _S45_PAIR in _s45_capped.reason)
|
||||
check("...and the transposed sentence is NOT what it says, so the check above "
|
||||
"discriminates rather than decorates - both numbers are in the string "
|
||||
"either way and a substring test would pass under the swap",
|
||||
_S45_SWAP not in _s45_capped.reason)
|
||||
check("...and it names the guard and the two spec sections, so the sentence "
|
||||
"cannot be read as a pack limit or a price limit",
|
||||
"CAPACITY-TARIFF GUARD" in _s45_capped.reason
|
||||
and "§9.1" in _s45_capped.reason and "§10.1" in _s45_capped.reason)
|
||||
check("...and an UNCAPPED trade does not carry that clause at all: a sentence "
|
||||
"that always says 'sized by the guard' tells nobody anything",
|
||||
"CAPACITY-TARIFF GUARD" not in _s45_clear.reason
|
||||
and f"charging {MAX_W:.0f} W" in _s45_clear.reason)
|
||||
|
||||
# --- the two refusals, and they are told apart from the ones that existed ---
|
||||
_s45_none = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER, headroom=None)
|
||||
_s45_zero = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER, headroom=0.0)
|
||||
print(f" headroom None -> {_s45_none.action}; headroom 0 W -> "
|
||||
f"{_s45_zero.action}")
|
||||
check("a headroom nothing MEASURED refuses. This is guard_state()'s None "
|
||||
"argument one layer down: charging creates the billed quantity (§9.1) "
|
||||
"and an unmeasured quarter is not a clear one",
|
||||
not _s45_none.trading
|
||||
and _s45_none.reason == _arb.IDLE_HEADROOM_UNMEASURED)
|
||||
check("...and it is DISTINGUISHABLE from the guard never having run at all, so "
|
||||
"the status page does not report a missing battery sensor as a missing "
|
||||
"meter", _s45_none.reason != _arb.IDLE_NOT_COVERED)
|
||||
check("a headroom of ZERO refuses rather than filing a 0 W claim - "
|
||||
"`Claim.set(..., 0.0)` at P_ARBITRAGE is a PARK ORDER that outranks the "
|
||||
"loop, which is the failure claim()'s own note is written against",
|
||||
not _s45_zero.trading and claim(_s45_zero) is None
|
||||
and _s45_zero.reason == _arb.IDLE_NO_HEADROOM)
|
||||
# ⚠️ TEST-16's RULE: TWO RUNGS THAT CAN ANSWER THE SAME STIMULUS MUST BE
|
||||
# SEPARATED. `charge_w = 0` and `headroom = 0` both produce a 0 W sizing, and
|
||||
# grading only `kind == "refused"` would let either absorb the other's work -
|
||||
# after which weakening either one reports nothing. So the REASONS are graded,
|
||||
# and each rung is reached with the other one clear.
|
||||
_s45_nosize = decide(PLAN, hour(CHEAP_H), peak_guard_active=False, soc=50.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=0.0, discharge_w=MAX_W,
|
||||
soc_floor_pct=20.0, soc_ceiling_pct=95.0)
|
||||
check("...and the PACK being sized at 0 W still reports OPT-09's own sentence, "
|
||||
"not this card's: the two rungs answer the same stimulus and a refusal "
|
||||
"that named the wrong subsystem would send an operator to the wrong page",
|
||||
not _s45_nosize.trading
|
||||
and _s45_nosize.reason == _arb.IDLE_NO_SIZE
|
||||
and _s45_zero.reason != _s45_nosize.reason)
|
||||
|
||||
# --- §9.1: the SELL leg is untouched ---------------------------------------
|
||||
_s45_sell = act(PLAN, DEAR_H, thresh=_shipped, unc=NO_WEATHER, headroom=0.0)
|
||||
check("a ZERO headroom does not cap a DISCHARGE. §9.1: 'discharge and export "
|
||||
"are never capped by the peak guard; only charging and import are' - the "
|
||||
"capacity tariff bills offtake, and a sell creates none",
|
||||
_s45_sell.action == DISCHARGE and near(_s45_sell.power_w, MAX_W))
|
||||
|
||||
# --- and main.py actually passes it, pinned on the AST ----------------------
|
||||
# ⚠️ THE CALL SITE IS THE UNIT OF COVERAGE (MUTATION.md habit 15). Nothing
|
||||
# behavioural in this file can see main.py drop the argument - every check
|
||||
# above calls decide() itself - and a required keyword-only parameter that no
|
||||
# caller fills is a TypeError only on the one path a suite does not run. Same
|
||||
# pin, same reason, as `weights=` in test_packshare.py part 10.
|
||||
_S45_MAIN = open(os.path.join(HERE, "app", "main.py"), encoding="utf-8").read()
|
||||
_s45_calls = [n for n in ast.walk(ast.parse(_S45_MAIN))
|
||||
if isinstance(n, ast.Call)
|
||||
and ast.unparse(n.func).endswith("arbitrage.decide")]
|
||||
_s45_arg = [ast.unparse(k.value) for c in _s45_calls for k in c.keywords
|
||||
if k.arg == "charge_headroom_w"]
|
||||
print(f" main.py has {len(_s45_calls)} `arbitrage.decide(` call site(s); "
|
||||
f"charge_headroom_w= is {_s45_arg}")
|
||||
check("main.py passes the guard's OWN measured headroom at its one "
|
||||
"arbitrage.decide() call site - the shipped expression, not a "
|
||||
"transcription of it, so a mutation back to a literal or to max_w is red "
|
||||
"rather than silent",
|
||||
_s45_arg == ["peakguard.charge_headroom_w(self.peak_guard)"])
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
print()
|
||||
print("3c. SAFETY-45 - THE REGRESSION: the closed loop SETTLES")
|
||||
# ---------------------------------------------------------------------------
|
||||
# ⚠️ THIS IS THE CHECK THE CARD IS ACTUALLY ABOUT, AND A UNIT TEST ON decide()
|
||||
# IS NOT IT. The defect is an INTERACTION - two strategies, a 900 s integrator
|
||||
# and a plant that answers back - and every individual decision in it was
|
||||
# correct. So the loop is closed here: prices decide, the battery model
|
||||
# responds, the shipped QuarterAverager reports the consequence, and the
|
||||
# shipped guard reacts to that.
|
||||
#
|
||||
# WHAT IS REAL, AND WHAT IS MODELLED - the same discipline TEST-23 stage 3's
|
||||
# harness holds itself to, because a transcription proves what somebody typed:
|
||||
#
|
||||
# REAL peakguard.decide/claim/charge_headroom_w, arbitrage.decide/claim/
|
||||
# guard_state, control.compute + Tuning, arbiter.resolve, and
|
||||
# p1.QuarterAverager - the billed-quarter accumulator itself, so the
|
||||
# quarters reported below are the ones a meter would bill.
|
||||
# MODEL ONE cycle's ORDER (peak block, then arbitrage reading its
|
||||
# conclusion, then the loop claim, then resolve) - twelve lines
|
||||
# transcribed from main.py:2660-2900 and pinned above in 3b; the
|
||||
# PLANT, an 800 W/s ramp into a 10 s first-order lag, which is
|
||||
# plantsim's; and a flat synthetic house.
|
||||
#
|
||||
# ⚠️ AND THE HEADLINE NUMBERS WERE NOT TAKEN HERE. They were taken on the
|
||||
# closed rig at /home/homelab/test23s3 against the shipped container's own
|
||||
# checkout, which is where a divergence between this model and main.py's real
|
||||
# event loop would show up. This section exists so CI can go red.
|
||||
# ---------------------------------------------------------------------------
|
||||
S45_CAP_W, S45_LOAD_W, S45_CYCLE_S, S45_RUN_S = 1500.0, 1200.0, 5.0, 2700.0
|
||||
S45_RAMP_W_S, S45_LAG_S = 800.0, 10.0
|
||||
# ⚠️ THE RUN STARTS ON A QUARTER BOUNDARY AND ENDS INSIDE THE SAME CHEAP HOUR,
|
||||
# and both halves matter. Starting on the boundary makes the three closed
|
||||
# blocks below whole billed quarters. Ending inside the hour keeps TEST-23
|
||||
# finding 1 - the export overshoot at the END of any trade, ~0.37 x max_w, a
|
||||
# separate and already-recorded property - out of a swing figure this card is
|
||||
# grading. The run still crosses TWO quarter boundaries, which is the half of
|
||||
# the defect the card says arbitrage must learn from.
|
||||
S45_T0 = D0 + timedelta(hours=CHEAP_H)
|
||||
|
||||
|
||||
def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
|
||||
seconds=S45_RUN_S):
|
||||
"""One closed hour. `sized=False` is the behaviour this card removes.
|
||||
|
||||
⚠️ THE COUNTERFACTUAL IS ONE ARGUMENT, NOT A SECOND CODE PATH. `sized=False`
|
||||
hands `decide()` a headroom nothing can bind - which is exactly what the
|
||||
tree did before this card, because nothing was passing one - so the two runs
|
||||
below differ in one value and share every line of shipped code. Habit 7.
|
||||
"""
|
||||
avg = QuarterAverager(phases=1, max_hold_s=900.0)
|
||||
tuning = Tuning(gain=0.6, max_w=MAX_W, slew_w=0.0)
|
||||
t0 = S45_T0
|
||||
target = i_w = 0.0
|
||||
sat = 0
|
||||
loop_w = None
|
||||
batt_cmd = batt = 0.0 # + discharge, as main.py's site_batt_w
|
||||
onsets = blocks = 0
|
||||
prev_action = "<start>"
|
||||
grid_lo, grid_hi = None, None
|
||||
billed = []
|
||||
acc = 0.0
|
||||
t = 0.0
|
||||
while t <= seconds:
|
||||
grid = load_w - batt
|
||||
imp, exp = split_signed(grid)
|
||||
for b in avg.add(make_sample("ha_signed", imp, exp, phases=1,
|
||||
ingest_ts=t0 + timedelta(seconds=t),
|
||||
ingest_mono=(t0.timestamp() + t))):
|
||||
billed.append(round(float(b.offtake_avg_w), 1))
|
||||
blocks += 1
|
||||
if acc <= 1e-9:
|
||||
acc = S45_CYCLE_S
|
||||
now = t0 + timedelta(seconds=t)
|
||||
claims = []
|
||||
pk = _pg.decide(PeakTracker.project(avg, now), batt_w=batt,
|
||||
cap_w=cap_w, reading=None, achievable_w=MAX_W,
|
||||
soc=50.0, soc_floor=20.0, max_hold_s=900.0,
|
||||
frozen=False)
|
||||
pc = _pg.claim(pk)
|
||||
if pc is not None:
|
||||
claims.append(pc)
|
||||
arb = decide(PLAN, now,
|
||||
peak_guard_active=_arb.guard_state(pk),
|
||||
charge_headroom_w=(_pg.charge_headroom_w(pk) if sized
|
||||
else HEADROOM_CLEAR),
|
||||
soc=50.0, min_spread_eur_kwh=_shipped,
|
||||
uncertainty=NO_WEATHER, charge_w=MAX_W,
|
||||
discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0)
|
||||
ac = claim(arb)
|
||||
if ac is not None:
|
||||
claims.append(ac)
|
||||
if arb.action == CHARGE and prev_action != CHARGE:
|
||||
onsets += 1
|
||||
prev_action = arb.action
|
||||
if loop_w is None or target != loop_w:
|
||||
i_w = target
|
||||
d = compute(prev_w=target, grid_w=grid, actual_w=batt,
|
||||
tuning=tuning, sat_count=sat, i_w=i_w)
|
||||
sat, i_w, loop_w = d.sat_count, d.i_w, d.target_w
|
||||
claims.append(Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W,
|
||||
"max_w"))
|
||||
claims.append(Claim.set("loop", P_LOOP, d.target_w, d.reason))
|
||||
target = resolve(claims).target_w
|
||||
# THE PLANT, MODELLED: an 800 W/s ramp into a 10 s first-order lag.
|
||||
step = min(1.0, acc)
|
||||
delta = target - batt_cmd
|
||||
batt_cmd += math.copysign(min(abs(delta), S45_RAMP_W_S * step), delta)
|
||||
batt += (batt_cmd - batt) * (step / S45_LAG_S)
|
||||
acc -= step
|
||||
t += step
|
||||
grid_lo = grid if grid_lo is None else min(grid_lo, grid)
|
||||
grid_hi = grid if grid_hi is None else max(grid_hi, grid)
|
||||
return dict(onsets=onsets, grid_lo=round(grid_lo, 1),
|
||||
grid_hi=round(grid_hi, 1), swing=round(grid_hi - grid_lo, 1),
|
||||
billed=billed, blocks=blocks)
|
||||
|
||||
S45_BEFORE = derived(lambda: s45_loop(sized=False))
|
||||
S45_AFTER = derived(lambda: s45_loop(sized=True))
|
||||
for _lab, _r in (("unsized (the shipped behaviour before this card)", S45_BEFORE),
|
||||
("sized by the guard", S45_AFTER)):
|
||||
print(f" {_lab}: {_r['onsets']} charge onsets/h, grid "
|
||||
f"{_r['grid_lo']:.0f} .. {_r['grid_hi']:.0f} W (swing "
|
||||
f"{_r['swing']:.0f} W), billed quarters {_r['billed']} W")
|
||||
|
||||
# ⚠️ THE NEGATIVE CONTROL FIRST. If the unsized run did NOT limit-cycle, every
|
||||
# assertion below would be a statement about a loop that was never unstable -
|
||||
# MUTATION.md's "a check whose data cannot reach the failure it names", which
|
||||
# has now appeared in eleven cards in this repository.
|
||||
check("PRECONDITION: with the trade UNSIZED this loop really does run away - "
|
||||
"many charge onsets in one hour and a grid swing of kilowatts. Without "
|
||||
"this, everything below grades a loop that was never unstable",
|
||||
S45_BEFORE["onsets"] >= 10 and S45_BEFORE["swing"] > 2000.0)
|
||||
check("...and it is the bang-bang shape and not a slow drift: the meter "
|
||||
"reaches both a hard import and an EXPORT, so the actuator is being "
|
||||
"handed back and forth rather than converging",
|
||||
S45_BEFORE["grid_hi"] > S45_CAP_W + 1000.0
|
||||
and S45_BEFORE["grid_lo"] < 0.0)
|
||||
check(f"THE REGRESSION: sizing the trade to the guard's measured headroom "
|
||||
f"settles the loop. {S45_BEFORE['onsets']} charge onsets an hour become "
|
||||
f"{S45_AFTER['onsets']}, and the grid swing falls from "
|
||||
f"{S45_BEFORE['swing']:.0f} W to {S45_AFTER['swing']:.0f} W",
|
||||
S45_AFTER["onsets"] <= 2
|
||||
and S45_AFTER["swing"] < 0.25 * S45_BEFORE["swing"])
|
||||
check("...and the battery is still TRADING for the whole hour rather than "
|
||||
"settling by giving up: §10.1 ranks peak shaving above arbitrage, it "
|
||||
"does not cancel it, and a fix that simply stopped buying would pass an "
|
||||
"onset count and fail the card",
|
||||
S45_AFTER["onsets"] == 1)
|
||||
check(f"...and every BILLED quarter comes in at or under the "
|
||||
f"{S45_CAP_W:.0f} W cap, which the unsized run does not manage - the "
|
||||
f"oscillation was not merely ugly, it was losing the money it was "
|
||||
f"oscillating about (§10.2, §9.1)",
|
||||
S45_AFTER["blocks"] >= 3
|
||||
and all(v <= S45_CAP_W + 0.5 for v in S45_AFTER["billed"])
|
||||
and any(v > S45_CAP_W for v in S45_BEFORE["billed"]))
|
||||
check("...and the two runs are the same code on the same fixture: one "
|
||||
"argument differs, and the loop, the guard, the arbiter, the averager "
|
||||
"and the plant are shared line for line",
|
||||
S45_BEFORE["blocks"] == S45_AFTER["blocks"])
|
||||
|
||||
# ⚠️ AND IT IS INERT WHERE THE DEFECT IS INERT, WHICH IS THE OTHER HALF OF A
|
||||
# FIX. The rig's sweep found the bite rule `load + max_w > peak_cap_w`; below
|
||||
# it, the trade never threatens the quarter and this card must change NOTHING.
|
||||
S45_WIDE = derived(lambda: s45_loop(sized=False, cap_w=5000.0, load_w=1200.0,
|
||||
seconds=900.0))
|
||||
S45_WIDE_S = derived(lambda: s45_loop(sized=True, cap_w=5000.0, load_w=1200.0,
|
||||
seconds=900.0))
|
||||
print(f" peak_cap_w 5000 W, 1200 W house (load + max_w = "
|
||||
f"{S45_LOAD_W + MAX_W:.0f} W, under the cap): unsized "
|
||||
f"{S45_WIDE['billed']} W, sized {S45_WIDE_S['billed']} W")
|
||||
check("on a site where the trade cannot reach the cap the two runs are "
|
||||
"IDENTICAL to the watt - so this card costs nothing on the installs it "
|
||||
"is not about, and the check above is not passing because the cap "
|
||||
"dominates everything",
|
||||
S45_WIDE == S45_WIDE_S and S45_WIDE["onsets"] == 1)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
print()
|
||||
print("4. §8.3 - no irreversible action on a provisional price")
|
||||
@@ -822,7 +1155,8 @@ _ticks = []
|
||||
for _t in range(24 * 120): # 24 h at the 30 s control cadence
|
||||
_d = decide(_flap_plan, D0 + timedelta(seconds=30 * _t),
|
||||
peak_guard_active=False, soc=50.0, min_spread_eur_kwh=_shipped,
|
||||
uncertainty=frozenset(), charge_w=MAX_W, discharge_w=MAX_W,
|
||||
uncertainty=frozenset(), charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=20.0, soc_ceiling_pct=95.0)
|
||||
_ticks.append(_d.action)
|
||||
_transitions = sum(1 for a, b in zip(_ticks, _ticks[1:]) if a != b)
|
||||
@@ -844,7 +1178,8 @@ _no_plan = act(None, CHEAP_H, thresh=_shipped)
|
||||
_no_soc = act(PLAN, CHEAP_H, thresh=_shipped, soc=None)
|
||||
_uncovered = decide(PLAN, D0 + timedelta(days=9), peak_guard_active=False,
|
||||
soc=50.0, min_spread_eur_kwh=_shipped,
|
||||
uncertainty=frozenset(), charge_w=MAX_W, discharge_w=MAX_W,
|
||||
uncertainty=frozenset(), charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=20.0, soc_ceiling_pct=95.0)
|
||||
_reasons = [_no_plan.reason, _no_soc.reason, _uncovered.reason, _blind.reason,
|
||||
_held.reason]
|
||||
@@ -1218,7 +1553,8 @@ def replay_real(days, threshold, unc, *, soc0=50.0, floor=20.0, ceiling=95.0):
|
||||
d = decide(plan, p.start + timedelta(minutes=30),
|
||||
peak_guard_active=False, soc=soc,
|
||||
min_spread_eur_kwh=threshold, uncertainty=unc,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=floor, soc_ceiling_pct=ceiling)
|
||||
if d.action is None:
|
||||
continue
|
||||
@@ -1952,10 +2288,12 @@ check("...and the same at the sell probe, against the verdict's dearest",
|
||||
_pa_sell is derived(lambda: _qv.dearest))
|
||||
_qbuy = decide(QPLAN, qprobe(Q_CHEAP_I), peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0)
|
||||
_qsell = decide(QPLAN, qprobe(Q_DEAR_I), peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0)
|
||||
check("...so decide() CHARGES in the cheapest quarter and DISCHARGES in the "
|
||||
@@ -1980,7 +2318,8 @@ check(f"the off-peak probe's own price differs from its hour's :00 price "
|
||||
and _QOFF_I not in (Q_CHEAP_I, Q_DEAR_I))
|
||||
_qoff = decide(QPLAN, qprobe(_QOFF_I), peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0)
|
||||
check("a quarter that is neither extremum still idles, for the reason that "
|
||||
"names the right rule, and reports ITS OWN price - not the price of the "
|
||||
@@ -2007,7 +2346,8 @@ check(f"the negative day's dearest quarter is slot {Q_DEAR_I} and it is BELOW "
|
||||
NO_WEATHER))
|
||||
_qneg_sell = decide(QNEG_PLAN, qprobe(Q_DEAR_I), peak_guard_active=False,
|
||||
soc=50.0, min_spread_eur_kwh=_shipped,
|
||||
uncertainty=NO_WEATHER, charge_w=MAX_W, discharge_w=MAX_W,
|
||||
uncertainty=NO_WEATHER, charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W,
|
||||
soc_floor_pct=20.0, soc_ceiling_pct=95.0)
|
||||
check("selling into a negative-price QUARTER is refused, and the reason names "
|
||||
"§17 and THAT QUARTER's price",
|
||||
@@ -2020,7 +2360,8 @@ check("...while the SAME quarter-hourly series with that ONE price's SIGN "
|
||||
"FLIPPED discharges instead",
|
||||
decide(qplan_of(QPOS), qprobe(Q_DEAR_I), peak_guard_active=False,
|
||||
soc=50.0, min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0).action == DISCHARGE
|
||||
and sum(1 for a, b in zip(QNEG, QPOS) if a != b) == 1)
|
||||
# §8.3's flag, read off the covering point. `_act`'s own provisional guard
|
||||
@@ -2077,11 +2418,13 @@ check("...so the mixed day CHARGES and DISCHARGES in its firm quarters, at "
|
||||
"their own prices",
|
||||
decide(MIX_PLAN, _mix_buy_t, peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0).action == CHARGE
|
||||
and decide(MIX_PLAN, _mix_sell_t, peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0).action == DISCHARGE)
|
||||
# An instant inside a CARRIED hour of the same series. The covering point is
|
||||
# the carried one; the shipped scan answered a point from the FIRM block
|
||||
@@ -2096,7 +2439,8 @@ check("an instant inside a CARRIED hour of the mixed series matches the "
|
||||
and MIX_PTS[MIX_N_H - 1].provisional is True
|
||||
and decide(MIX_PLAN, _mix_carried_t, peak_guard_active=False, soc=50.0,
|
||||
min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
charge_headroom_w=HEADROOM_CLEAR,
|
||||
charge_w=MAX_W, discharge_w=MAX_W, soc_floor_pct=20.0,
|
||||
soc_ceiling_pct=95.0).action is None)
|
||||
|
||||
print()
|
||||
|
||||
@@ -74,6 +74,7 @@ Read MUTATION.md before you report a survivor.
|
||||
import asyncio
|
||||
import io
|
||||
import math
|
||||
import re
|
||||
import sys
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
@@ -87,6 +88,7 @@ from app.arbiter import P_LOOP, Claim, UnitBounds, allocate, resolve
|
||||
from app.control import Tuning, compute
|
||||
from app.inverter import Inverter
|
||||
from app.main import Controller
|
||||
from app import shadow
|
||||
|
||||
fails = []
|
||||
T0 = datetime(2026, 8, 30, 9, 0, 0, tzinfo=timezone.utc)
|
||||
@@ -670,8 +672,15 @@ def arm(c, value):
|
||||
|
||||
async def _direct():
|
||||
hass = _Hass(0.0)
|
||||
# ⚠️ SAFETY-10: `shadow_mode: "off"` EXPLICITLY, BECAUSE THIS FIXTURE
|
||||
# NEVER PRESSES START. The shipped default is `auto`, which is SHADOW
|
||||
# MODE while control is stopped - so without this line the probe below
|
||||
# would be graded against a controller that is correctly refusing to
|
||||
# command anything, and the clamp it is here to exercise would never be
|
||||
# reached. The shipped write path is unaffected: a stopped controller
|
||||
# only ever writes 0 W in production, which shadow mode also writes.
|
||||
c = Controller({"setpoint_entity": "number.sp", "max_w": 2000,
|
||||
"meter_source": "off"},
|
||||
"meter_source": "off", "shadow_mode": "off"},
|
||||
hass, _Store(), _Pub(), stop=asyncio.Event())
|
||||
c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
|
||||
# The shape the heartbeat, shutdown() and handle_action() all use - each one
|
||||
@@ -1121,10 +1130,16 @@ A_UNIT, B_HYPO = "inverter-a", "inverter-b"
|
||||
|
||||
|
||||
def fresh(**over):
|
||||
"""A Controller with a stub HA, no cycle run, and therefore NO record."""
|
||||
"""A Controller with a stub HA, no cycle run, and therefore NO record.
|
||||
|
||||
⚠️ SAFETY-10: `shadow_mode: "off"` for `_direct()`'s reason - this fixture
|
||||
never presses Start, and the shipped default is shadow mode while control
|
||||
is stopped. Part 7 grades who is allowed to reach the WIRE; a controller
|
||||
that is correctly commanding nothing cannot answer that question.
|
||||
"""
|
||||
hass = _Hass(0.0)
|
||||
c = Controller(dict({"setpoint_entity": "number.sp", "max_w": 2000,
|
||||
"meter_source": "off"}, **over),
|
||||
"meter_source": "off", "shadow_mode": "off"}, **over),
|
||||
hass, _Store(), _Pub(), stop=asyncio.Event())
|
||||
c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
|
||||
return hass, c
|
||||
@@ -1414,6 +1429,432 @@ check("...and the numbers those cycles put on the wire are the arbiter's own "
|
||||
hass_r.writes and all(abs(w) <= LIVE_MAX_W for w in hass_r.writes))
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# 8. SAFETY-10 - SHADOW MODE: THE DECISION PATH RUNS AND NOTHING REACHES THE
|
||||
# INVERTER
|
||||
# --------------------------------------------------------------------------- #
|
||||
# This part belongs in THIS file and not in a new one: shadow mode is a
|
||||
# substitution inside `_write_unit()`, one line below SAFETY-03's clamp and two
|
||||
# below SAFETY-28's gate, and the property it claims - "nothing reaches the
|
||||
# inverter" - is the same property parts 5 and 7 already grade from the other
|
||||
# side. The fake `set_number()` in this file IS the wire.
|
||||
#
|
||||
# ⚠️ EVERY CHECK BELOW IS GRADED ON THE WRITES OR ON THE RENDERED SURFACE, NOT
|
||||
# ON `Controller.shadow`. A check that asserted the flag would pass on a build
|
||||
# in which the flag is set and the substitution is deleted, which is precisely
|
||||
# the build this section exists to refuse.
|
||||
#
|
||||
# ⚠️ AND EVERY ONE OF THEM RUNS THE SAME STIMULUS IN BOTH MODES. MUTATION.md's
|
||||
# rule: a per-thing check that has never seen the things DISAGREE is a total.
|
||||
# `_s10_live` and `_s10_shadow` are the same 6000 W import through the same
|
||||
# `Controller.cycle()`; the only difference is one option.
|
||||
print("\n8. SAFETY-10 - shadow mode\n")
|
||||
|
||||
|
||||
def _s10(shadow_mode, *, auto=True, cycles=25, grid=6000.0, dev=None, **over):
|
||||
"""The same wired run as part 3, with `shadow_mode` and the start button.
|
||||
|
||||
⚠️ `auto` IS A PARAMETER BECAUSE `shadow_mode: auto` READS IT. The three
|
||||
values and the two button positions are six states and they are not all
|
||||
the same state; the pure-function table over all six is in
|
||||
`test_validate.py`, and 8f says why it is not here.
|
||||
"""
|
||||
async def go():
|
||||
hass = _Hass(grid, track=True)
|
||||
c = Controller(dict(
|
||||
{"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
|
||||
"soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
|
||||
"meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
|
||||
"slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
|
||||
"step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
|
||||
"shadow_mode": shadow_mode},
|
||||
**over), hass, _Store(), _Pub(), stop=asyncio.Event())
|
||||
c.auto = auto
|
||||
# `dev` narrows what the DEVICE says it will accept, which is the
|
||||
# clamp's second stage - the only way to make the clamp engage on a
|
||||
# target the loop has already bounded at `max_w`.
|
||||
c.dev_min, c.dev_max = ((-LIVE_MAX_W, LIVE_MAX_W) if dev is None
|
||||
else (-dev, dev))
|
||||
# ⚠️ CAPTURED PER CYCLE, BECAUSE THE HEARTBEAT OVERWRITES IT.
|
||||
# `clamp_last` is assigned by every write, and the heartbeat below
|
||||
# writes `inv.target` - 0 W in shadow mode - so the clamp's verdict on
|
||||
# the DECISION is gone by the end of the run. Looking for it afterwards
|
||||
# would grade the refresh instead of the cycle.
|
||||
c.clamp_seen = []
|
||||
for n in range(cycles):
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
if c.clamp_last is not None:
|
||||
c.clamp_seen.append(c.clamp_last)
|
||||
# ⚠️ THE HEARTBEAT IS DRIVEN HERE AND NOT LEFT OUT, BECAUSE IT IS
|
||||
# THE HALF THAT PROVES SHADOW MODE IS NOT SILENCE. `_write_unit()`
|
||||
# skips an unchanged value unless `force` is set, so a cycles-only
|
||||
# fixture sees exactly ONE 0 W write and could not tell "holds the
|
||||
# inverter at 0 W" from "wrote 0 W once and went quiet" - and the
|
||||
# second of those leaves a real install's ESP32 in a tripped
|
||||
# stale-input watchdog for the whole run. `heartbeat_s=0` makes
|
||||
# every tick due, which is the shipped path with its clock wound
|
||||
# forward rather than a second implementation of it.
|
||||
await c.send_heartbeats(float(n), 0.0)
|
||||
return hass, c
|
||||
return asyncio.run(go())
|
||||
|
||||
|
||||
_live_h, _live_c = _s10("off")
|
||||
_shad_h, _shad_c = _s10("on")
|
||||
|
||||
# --- 8a. THE PRECONDITION, WHICH IS THE HALF THAT MAKES THE REST MEAN ANYTHING
|
||||
# MUTATION.md habit 4: a check whose DATA cannot reach the failure it names is
|
||||
# decoration. "No non-zero value was written" is trivially true of a stimulus
|
||||
# that would not have produced one, so the same stimulus is first shown to
|
||||
# produce a large one with the option off.
|
||||
check("PRECONDITION: with shadow_mode off this stimulus really does drive the "
|
||||
f"wire - {len(_live_h.writes)} writes, "
|
||||
f"{len([w for w in _live_h.writes if w != 0.0])} of them non-zero, "
|
||||
f"largest {max((abs(w) for w in _live_h.writes), default=0):.0f} W",
|
||||
len([w for w in _live_h.writes if w != 0.0]) >= 10
|
||||
and max((abs(w) for w in _live_h.writes), default=0) > 1000.0
|
||||
and 0.0 not in _live_h.writes)
|
||||
|
||||
# --- 8b. NOTHING THE DECISION PATH PRODUCED REACHES THE INVERTER -------------
|
||||
check("AC 1: in shadow mode EVERY value that reached set_number() is 0 W. "
|
||||
f"Distinct values written: {sorted(set(_shad_h.writes))}",
|
||||
_shad_h.writes and set(_shad_h.writes) == {0.0})
|
||||
|
||||
# ⚠️ AND IT IS NOT SILENCE. The inverter holds its last command forever and the
|
||||
# ESP32's stale-input watchdog needs a refresh; a shadow mode that stopped
|
||||
# writing would leave a standing command up under a page saying nothing is
|
||||
# commanded. A check that only asserted "no non-zero write" would pass on that
|
||||
# build too - this is the half that separates them.
|
||||
check("...and it WROTE that 0 W rather than going silent, which is what keeps "
|
||||
f"the inverter from holding its last command ({len(_shad_h.writes)} "
|
||||
"writes)",
|
||||
len(_shad_h.writes) >= 2)
|
||||
|
||||
# --- 8c. THE DECISION PATH ACTUALLY RAN ------------------------------------
|
||||
# "Nothing reached the inverter" is also true of a controller that decided
|
||||
# nothing. Both halves, or the feature is an off switch with a long name.
|
||||
check("the full decision path still ran: the loop reached a target and the "
|
||||
f"arbiter resolved one ({_shad_c.loop_w!r} W, "
|
||||
f"would have commanded {_shad_c.shadow_would_w!r} W)",
|
||||
_shad_c.loop_w is not None and abs(_shad_c.loop_w) > 500.0
|
||||
and _shad_c.shadow_would_w is not None
|
||||
and abs(_shad_c.shadow_would_w) > 500.0)
|
||||
check("...and the decision it recorded is a number a live controller would "
|
||||
"have written - it is inside the rail and it is not the 0 W that went "
|
||||
"on the wire",
|
||||
_shad_c.shadow_would_w != 0.0
|
||||
and abs(_shad_c.shadow_would_w) <= LIVE_MAX_W)
|
||||
|
||||
# --- 8d. THE CARRIED COMMAND TRACKS THE WIRE, WHICH IS WHAT MAKES THE EXIT
|
||||
# SAFE
|
||||
check("the carried site command is what is STANDING ON THE WIRE, not the "
|
||||
f"decision ({_shad_c.target!r} W standing, "
|
||||
f"{_shad_c.shadow_would_w!r} W decided)",
|
||||
_shad_c.target == 0.0 and _shad_c.shadow_would_w != 0.0)
|
||||
check("...and every unit's share is too, so SAFETY-42's delivery watchdog is "
|
||||
"not handed a share nothing was told to produce",
|
||||
all(i.target == 0.0 for i in _shad_c.inverters))
|
||||
|
||||
|
||||
def _s10_exit(shadow_first):
|
||||
"""Run twelve cycles, force shadow mode off, take ONE more cycle.
|
||||
|
||||
Answers with `inv.last_write` either side of that boundary - WHAT STANDS ON
|
||||
THE WIRE, updated only on an accepted write, which is the number the
|
||||
inverter is actually latched on. Reading `hass.writes` instead would be
|
||||
blind to the converged case, where the controller correctly re-sends
|
||||
nothing at all.
|
||||
|
||||
⚠️ THE COMPARISON IS AGAINST THE SAME RUN THAT NEVER ENTERED SHADOW MODE,
|
||||
not against a constant. `slew_w` bounds a step from the standing command,
|
||||
so "did it resume from the wire or from a fiction" is a question about a
|
||||
DIFFERENCE, and a hard-coded expectation would be the number the code
|
||||
produces compared with itself.
|
||||
"""
|
||||
async def go():
|
||||
hass = _Hass(6000.0, track=True)
|
||||
c = Controller(
|
||||
{"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
|
||||
"soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
|
||||
"meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
|
||||
"slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
|
||||
"step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
|
||||
"shadow_mode": "on" if shadow_first else "off"},
|
||||
hass, _Store(), _Pub(), stop=asyncio.Event())
|
||||
c.auto = True
|
||||
c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
|
||||
for _ in range(12):
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
before = c.inverters[0].last_write
|
||||
c.o["shadow_mode"] = "off"
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
# ⚠️ NOT `float()`. `last_write` is None until something is ACCEPTED,
|
||||
# and a build in which shadow mode writes nothing at all would turn
|
||||
# this fixture into a TypeError - which MUTATION.md's FCST-06 section
|
||||
# is about: a traceback grades none of the checks after it AND reads
|
||||
# like a survivor. It is handed back as None and named below instead.
|
||||
return before, c.inverters[0].last_write, c
|
||||
return asyncio.run(go())
|
||||
|
||||
|
||||
_exit_before, _exit_after, _exit_c = _s10_exit(True)
|
||||
_never_before, _never_after, _never_c = _s10_exit(False)
|
||||
print(f" shadow run: standing {_exit_before!r} W -> {_exit_after!r} W on "
|
||||
"the first live cycle")
|
||||
print(f" never in shadow: standing {_never_before!r} W -> "
|
||||
f"{_never_after!r} W on the same cycle")
|
||||
check("SOMETHING REACHED THE WIRE IN SHADOW MODE. `last_write` is set only on "
|
||||
"an ACCEPTED write, so None here is the build that stops writing "
|
||||
"altogether and leaves the inverter latched on its last command - the "
|
||||
"failure shadow mode must not be a new way to reach",
|
||||
_exit_before is not None and _exit_after is not None
|
||||
and _never_before is not None and _never_after is not None)
|
||||
_exit_before = -1.0 if _exit_before is None else float(_exit_before)
|
||||
_exit_after = -1.0 if _exit_after is None else float(_exit_after)
|
||||
_never_before = 0.0 if _never_before is None else float(_never_before)
|
||||
_never_after = 0.0 if _never_after is None else float(_never_after)
|
||||
check("PRECONDITION: the two arrangements DISAGREE - the run that was never in "
|
||||
"shadow mode is standing somewhere else entirely at that boundary, so "
|
||||
"the comparison below is not a number against itself",
|
||||
_never_before != _exit_before and abs(_never_before) > 1000.0)
|
||||
check("PRECONDITION: and the shadow run really was standing at 0 W, so the "
|
||||
"step below is measured from the wire and not from a coincidence",
|
||||
_exit_before == 0.0)
|
||||
check("AC 2, leaving: the first live command after shadow mode is one slew "
|
||||
"step from the 0 W that was actually standing on the wire - NOT one step "
|
||||
"from the decision shadow mode reached, which never existed at the "
|
||||
f"battery. |{_exit_after:.0f}| <= slew 1000 W",
|
||||
abs(_exit_after) <= 1000.0)
|
||||
check("...and the run that was never in shadow mode is NOT inside that bound "
|
||||
"at the same cycle, which is what says the bound is a real constraint "
|
||||
"here and not a property of the stimulus",
|
||||
abs(_never_after) > 1000.0)
|
||||
|
||||
|
||||
def _s10_enter():
|
||||
"""Live first, then shadow mode, on a battery standing somewhere else."""
|
||||
async def go():
|
||||
hass = _Hass(6000.0, track=True)
|
||||
c = Controller(
|
||||
{"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
|
||||
"soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
|
||||
"meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
|
||||
"slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
|
||||
"step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
|
||||
"shadow_mode": "off"}, hass, _Store(), _Pub(),
|
||||
stop=asyncio.Event())
|
||||
c.auto = True
|
||||
c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
|
||||
for _ in range(12):
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
standing = hass.writes[-1]
|
||||
c.o["shadow_mode"] = "on"
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
# ⚠️ `inverters[0].last_write`, NOT `hass.writes[-1]`. The question is
|
||||
# WHAT THE INVERTER IS LATCHED ON after the first shadow cycle, and a
|
||||
# build that writes NOTHING leaves it latched on the live value while
|
||||
# `hass.writes[-1]` still reads that same number - the two look
|
||||
# identical from the write list and are opposite at the battery.
|
||||
return standing, float(c.inverters[0].last_write), c
|
||||
return asyncio.run(go())
|
||||
|
||||
|
||||
_stood, _first_shadow, _enter_c = _s10_enter()
|
||||
print(f" standing when shadow mode came on: {_stood:.0f} W")
|
||||
check("PRECONDITION: the battery was standing at a real, non-zero command when "
|
||||
"shadow mode was switched on - otherwise 'it reached 0 W' says nothing",
|
||||
abs(_stood) > 500.0)
|
||||
check("AC 2, entering: after ONE shadow cycle the inverter is latched on 0 W, "
|
||||
"not on what it was doing a cycle earlier. The inverter holds its last "
|
||||
"command FOREVER, so a shadow mode that merely stopped writing would "
|
||||
"leave that command standing under a page saying nothing is commanded "
|
||||
f"({_stood:+.0f} W -> {_first_shadow:+.0f} W)",
|
||||
_first_shadow == 0.0)
|
||||
|
||||
# --- 8e. THE OTHER GUARDS ON THE WRITE PATH STILL OBSERVE --------------------
|
||||
# The substitution is the LAST thing before the wire, below SAFETY-28's gate and
|
||||
# below SAFETY-03's clamp, so both still grade the number the decision path
|
||||
# produced. A shadow run that could not say "it would have hit the rating here"
|
||||
# is answering a different question from the one it is for.
|
||||
_cl_h, _cl_c = _s10("on", cycles=12, grid=9000.0, dev=400.0)
|
||||
_cl_req = [r.requested_w for r in _cl_c.clamp_seen]
|
||||
print(f" decision {_cl_c.shadow_would_w!r} W; what the clamp was asked "
|
||||
f"about at each cycle boundary: {sorted(set(_cl_req))}")
|
||||
check("PRECONDITION: the decision is a real, non-zero number and the wire "
|
||||
"carried only 0 W on this run, so the two are distinguishable",
|
||||
_cl_c.shadow_would_w is not None and _cl_c.shadow_would_w != 0.0
|
||||
and set(_cl_h.writes) == {0.0})
|
||||
check("SAFETY-03 still OBSERVES in shadow mode: the clamp was asked about the "
|
||||
"number THE DECISION PATH PRODUCED, not about the 0 W that went on the "
|
||||
"wire. That is what puts the substitution BELOW the clamp, and it is "
|
||||
"what lets a shadow run report that the rating would have been hit",
|
||||
_cl_req and all(r == _cl_c.shadow_would_w for r in _cl_req))
|
||||
check("...and the clamp's own alarm still ran on it - the winding-loop "
|
||||
"engagement reached the action log on a run where nothing was commanded",
|
||||
any("clamp" in e.lower() or "CLAMP" in e for e in _cl_c.events))
|
||||
check("SAFETY-28's gate still OBSERVES too - it refused nothing on this run, "
|
||||
"which is the same answer it gives live, so shadow mode has not been "
|
||||
"implemented by making every write unauthorised",
|
||||
not [e for e in _cl_c.events if "WRITE REFUSED" in e])
|
||||
|
||||
# ⚠️ AND SAFETY-18 IS GRADED ON WHAT IT WAS HANDED, WHICH IS AN ORDERING
|
||||
# CLAIM. `check_meter_frozen()` takes `self.target` - the arbiter's RESOLVED
|
||||
# INTENT - and `_shadow_settle()` re-seeds that to 0 W at the very end of the
|
||||
# cycle, AFTER it. Re-seed one line earlier and the freeze detector grades a
|
||||
# 0 W that no decision produced: its conjunction needs a command at the rail,
|
||||
# so it goes permanently blind and the whole suite stays green. The detector's
|
||||
# own `evaluate` is wrapped here because the arguments are the only place that
|
||||
# ordering is observable.
|
||||
_fz_seen = []
|
||||
_fz_real = _shad_c.freeze_wd.evaluate
|
||||
|
||||
|
||||
def _fz_spy(unchanged, target, *a, **k):
|
||||
_fz_seen.append(target)
|
||||
return _fz_real(unchanged, target, *a, **k)
|
||||
|
||||
|
||||
_shad_c.freeze_wd.evaluate = _fz_spy
|
||||
|
||||
|
||||
async def _one_more():
|
||||
await _shad_c.read_inputs()
|
||||
await _shad_c.cycle()
|
||||
|
||||
|
||||
asyncio.run(_one_more())
|
||||
_shad_c.freeze_wd.evaluate = _fz_real
|
||||
print(f" SAFETY-18 was handed: {_fz_seen}")
|
||||
check("PRECONDITION: the freeze detector was consulted at all on that cycle",
|
||||
len(_fz_seen) == 1)
|
||||
check("SAFETY-18 still OBSERVES the DECISION: it is handed the arbiter's "
|
||||
"resolved intent, not the 0 W the wire gate substituted. Re-seeding one "
|
||||
"line earlier would hand it a command no decision produced and its "
|
||||
"conjunction - a command at the rail against a meter that has stopped "
|
||||
"moving - could never be satisfied again",
|
||||
_fz_seen and _fz_seen[0] == _shad_c.shadow_would_w
|
||||
and _fz_seen[0] != shadow.WIRE_W)
|
||||
|
||||
# --- 8f. THE MODE TABLE LIVES IN test_validate.py ---------------------------
|
||||
# `shadow.engaged()` is a pure function of the option and the start button, and
|
||||
# the six states it answers for are graded beside the rule that validates the
|
||||
# option - not here, where a defeat of the DEFAULT stops part 3's wired run
|
||||
# reaching the wire at all and takes this whole file down before part 8 runs.
|
||||
# ⚠️ THAT IS MEASURED, NOT ANTICIPATED: the mutation that makes `auto` resolve
|
||||
# to shadow unconditionally aborts part 3 with an IndexError, so its red count
|
||||
# here is a LOWER BOUND and none of part 8 is graded (MUTATION.md, FCST-06).
|
||||
|
||||
# --- 8g. THE OPERATOR STOP, WHICH IS THE ONE FAILSAFE THIS CARD CHANGES ------
|
||||
_stop_live_h, _stop_live_c = _s10("off", auto=False, cycles=6)
|
||||
_stop_shad_h, _stop_shad_c = _s10("auto", auto=False, cycles=6)
|
||||
print(f" stopped, shadow off: {_stop_live_c.reason!r}")
|
||||
print(f" stopped, shadow on : {_stop_shad_c.reason!r}")
|
||||
check("PRECONDITION: with shadow mode off, a stopped controller files the "
|
||||
"P_SAFETY stop claim and the arbiter resolves to THAT source, at 0 W",
|
||||
_stop_live_c.reason.startswith("safety")
|
||||
and _stop_live_c.target == 0.0)
|
||||
check("in shadow mode that claim is NOT filed, so the arbiter resolves to the "
|
||||
"REAL winner and the recorded decision is the real one. A P_SAFETY claim "
|
||||
"out-ranks everything - left in, every shadow run would answer the wrong "
|
||||
f"question ({_stop_shad_c.reason!r})",
|
||||
_stop_shad_c.reason.startswith("loop")
|
||||
and _stop_shad_c.shadow_would_w is not None
|
||||
and abs(_stop_shad_c.shadow_would_w) > 0.0)
|
||||
check("...and the actuator ends at exactly the same place either way, because "
|
||||
"the substitution that replaced the claim is STRICTLY STRONGER: a claim "
|
||||
"can be out-ranked and a wire gate cannot",
|
||||
set(_stop_shad_h.writes) == {0.0} == set(_stop_live_h.writes))
|
||||
|
||||
# --- 8h. THE RENDERED SURFACE (TARIFF-11's pattern) -------------------------
|
||||
# Graded on `status_payload()`, which IS the status page: web.py's `PAGE` is a
|
||||
# static shell whose banner and rows are filled from this JSON. Named slots, not
|
||||
# substring tests, so a transposition moves a slot.
|
||||
_ROW = "Shadow mode"
|
||||
_shad_pay = _shad_c.status_payload()
|
||||
_live_pay = _live_c.status_payload()
|
||||
_shad_rows = dict(_shad_pay["rows"])
|
||||
_live_rows = dict(_live_pay["rows"])
|
||||
print(f" banner: {_shad_pay['banner']!r}")
|
||||
print(f" row : {_shad_rows.get(_ROW)!r}")
|
||||
check("the status page has a Shadow mode row in BOTH states, so its ABSENCE is "
|
||||
"never how an operator learns which one they are in",
|
||||
_ROW in _shad_rows and _ROW in _live_rows)
|
||||
check("AC 3: the banner states plainly that the battery is not being "
|
||||
"controlled",
|
||||
"SHADOW MODE" in _shad_pay["banner"]
|
||||
and "NOT being controlled" in _shad_pay["banner"])
|
||||
check("...and it is not green. A page that reads `ok` while nothing is being "
|
||||
"commanded is the 'looks healthy but is inert' failure itself",
|
||||
_shad_pay["level"] == "warn")
|
||||
check("...and it is FIRST in the cascade: the same controller has other "
|
||||
"conditions to report and none of them displaces this sentence",
|
||||
_live_pay["banner"] != _shad_pay["banner"]
|
||||
and "SHADOW MODE" not in _live_pay["banner"])
|
||||
_slot = re.search(r"WOULD HAVE COMMANDED ([-+][\d ]+) W, inverter held at "
|
||||
r"([-\d]+) W", _shad_rows[_ROW])
|
||||
check("the row answers 'what would it have done' with a NUMBER in its own "
|
||||
"named slot, and says where the inverter actually is in a second one - "
|
||||
"two slots in one sentence, so a transposition moves them",
|
||||
_slot is not None)
|
||||
if _slot is not None:
|
||||
_would = float(_slot.group(1).replace(" ", ""))
|
||||
check("...and that number is the decision the path reached, not the 0 W "
|
||||
f"standing on the wire ({_would:.0f} vs {_shad_c.target:.0f})",
|
||||
_would == round(float(_shad_c.shadow_would_w))
|
||||
and _would != _shad_c.target)
|
||||
check("...and the second slot is the STANDING command, so the two cannot "
|
||||
"be read as one number",
|
||||
float(_slot.group(2)) == 0.0)
|
||||
check("the row answers 'and why' by carrying the arbiter's own sentence, "
|
||||
"rather than a re-derivation of it",
|
||||
_shad_c.reason in _shad_rows[_ROW])
|
||||
check("with shadow mode off the row says so, and says what follows from it - "
|
||||
"which is the arrangement that makes the one above a claim about this "
|
||||
"controller and not about the string",
|
||||
"NOT in shadow mode" in _live_rows[_ROW]
|
||||
and "DOES reach the inverter" in _live_rows[_ROW]
|
||||
and "WOULD HAVE COMMANDED" not in _live_rows[_ROW])
|
||||
|
||||
# ⚠️ A STANDING LATCH IS NAMED RATHER THAN HIDDEN. The shadow banner sits above
|
||||
# the three `bad` branches, so it has to carry what they would have said - a
|
||||
# latch that is up while the controller is inert is up the moment it stops
|
||||
# being inert.
|
||||
_shad_c.inverters[0].sign_wd.tripped = True
|
||||
_latched = _shad_c.status_payload()
|
||||
print(f" banner with a latch up: {_latched['banner']!r}")
|
||||
check("a failsafe latch that is standing is NAMED in the shadow banner and "
|
||||
"turns it red, so nobody turns shadow mode off into a battery that will "
|
||||
"not move and a page that never mentioned why",
|
||||
_latched["level"] == "bad"
|
||||
and "LATCH IS STILL UP" in _latched["banner"]
|
||||
and _shad_c.inverters[0].name in _latched["banner"])
|
||||
check("...and it still says the battery is not being controlled, so the latch "
|
||||
"has not displaced the sentence that may never be displaced",
|
||||
"NOT being controlled" in _latched["banner"])
|
||||
_shad_c.inverters[0].sign_wd.tripped = False
|
||||
|
||||
# --- 8i. THE RECORD A LATER ANALYSIS READS ----------------------------------
|
||||
# A shadow run is only worth running if it answers "what would it have done,
|
||||
# and why" AFTERWARDS, from the 40-row action log, and not only on a page
|
||||
# somebody happened to be looking at.
|
||||
_shadow_lines = [e for e in _shad_c.events if "SHADOW" in e]
|
||||
print(f" action log, shadow lines: {len(_shadow_lines)} of "
|
||||
f"{len(_shad_c.events)}")
|
||||
check("the action log records that shadow mode came on, in words",
|
||||
any("SHADOW MODE ON" in e for e in _shadow_lines))
|
||||
check("...and what it would have commanded, with the arbiter's reason beside "
|
||||
"it",
|
||||
any("would have commanded" in e and "loop" in e for e in _shadow_lines))
|
||||
check("...EDGE-logged, not level-logged: 25 cycles did not flush the 40-row "
|
||||
"log that has to carry the context of what the run found",
|
||||
len(_shadow_lines) < 25 and len(_shad_c.events) <= 40)
|
||||
|
||||
|
||||
print()
|
||||
if fails:
|
||||
print(f"{len(fails)} FAILED: {', '.join(fails)}")
|
||||
|
||||
@@ -224,9 +224,18 @@ A_RATING = 5000.0
|
||||
# had become so; validate.py rule 10 refused it the day it existed, which is
|
||||
# what a rule about a relationship is for. 0 means "follow the rail"
|
||||
# (`control.SLEW_RAIL_FRAC * max_w`) and is what config.yaml ships.
|
||||
# ⚠️ SAFETY-10: `shadow_mode="off"` EXPLICITLY, BECAUSE NOTHING HERE PRESSES
|
||||
# START. The shipped default is `auto`, which is SHADOW MODE while control is
|
||||
# stopped - and in shadow mode every write is substituted with 0 W at the one
|
||||
# choke point these parts grade. Without this line the per-unit clamp, the
|
||||
# per-unit write budget and the per-unit heartbeat would all be measured on a
|
||||
# controller that is correctly refusing to command anything, which is a
|
||||
# different (and vacuous) claim. The shipped write path is unaffected: a
|
||||
# stopped controller only ever writes 0 W in production anyway.
|
||||
BASE_OPTS = dict(A_ENT, meter_source="off", meter_entity="sensor.grid",
|
||||
max_w=A_RATING, gain=0.6, slew_w=0, deadband_w=15,
|
||||
target_grid_w=0, step_w=10, heartbeat_s=10, stale_input_s=15)
|
||||
target_grid_w=0, step_w=10, heartbeat_s=10, stale_input_s=15,
|
||||
shadow_mode="off")
|
||||
|
||||
|
||||
def built(opts=None, store=None, hass=None, second=None):
|
||||
|
||||
@@ -1067,14 +1067,19 @@ class _V:
|
||||
|
||||
_here = _Pt(_NOW)
|
||||
_other = _Pt(_NOW - timedelta(hours=3))
|
||||
# SAFETY-45's `headroom_w` is the last positional. It is set to a value that
|
||||
# CANNOT BIND on either call - larger than every sizing below - so this part
|
||||
# goes on grading OPT-09's per-pack sizing and not the capacity-tariff cap that
|
||||
# now sits beside it. test_arbitrage.py section 3b is where it is made to bind.
|
||||
_CLEAR_W = 1e9
|
||||
_sell = arbitrage._act(_Plan(_here), _NOW, _V(_other, _here), 60.0,
|
||||
0.0, 0.0, 20.0, 90.0)
|
||||
0.0, 0.0, 20.0, 90.0, _CLEAR_W)
|
||||
_sell_ok = arbitrage._act(_Plan(_here), _NOW, _V(_other, _here), 60.0,
|
||||
0.0, 4600.0, 20.0, 90.0)
|
||||
0.0, 4600.0, 20.0, 90.0, _CLEAR_W)
|
||||
_buy = arbitrage._act(_Plan(_here), _NOW, _V(_here, _other), 60.0,
|
||||
0.0, 0.0, 20.0, 90.0)
|
||||
0.0, 0.0, 20.0, 90.0, _CLEAR_W)
|
||||
_buy_ok = arbitrage._act(_Plan(_here), _NOW, _V(_here, _other), 60.0, 5000.0,
|
||||
0.0, 20.0, 90.0)
|
||||
0.0, 20.0, 90.0, _CLEAR_W)
|
||||
print(f" sized at 0 W: sell -> {_sell.action}, buy -> {_buy.action}; "
|
||||
f"sized at a rating: sell -> {_sell_ok.action}, buy -> {_buy_ok.action}")
|
||||
check("⚠️ A TRADE NOTHING CAN TAKE IS NOT A TRADE. A 0 W sizing IDLES on both "
|
||||
|
||||
@@ -138,8 +138,8 @@ from app.peakguard import (
|
||||
BLIND_COVERAGE, BLIND_FROZEN, BLIND_NO_BLOCK, CEILING_CAP,
|
||||
CEILING_MONTH_PEAK, FLOOR_AT_SOC_FLOOR, FLOOR_SOC_UNREADABLE,
|
||||
PEAK_OPTION_DEFAULTS, Pack, PeakDecision, binding_soc_floor, blindness,
|
||||
decide, discharge_permitted, excess_w, pack_floor_pct, pack_permissions,
|
||||
quarter_ceiling_w, uncovered_s,
|
||||
charge_headroom_w, decide, discharge_permitted, excess_w, pack_floor_pct,
|
||||
pack_permissions, quarter_ceiling_w, uncovered_s,
|
||||
)
|
||||
from app.validate import validate_startup_config
|
||||
from app.tariff import (
|
||||
@@ -379,8 +379,17 @@ check("at the engagement boundary the excess is zero, so the floor is exactly "
|
||||
released = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
|
||||
achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
|
||||
would_release_on_excess = excess_w(p_edge, CEIL) <= 0.0
|
||||
# ⚠️ `floor_w` IS FORMATTED DEFENSIVELY, AND MUTATION.md's OWN LEDGER IS WHY.
|
||||
# The mutation this check exists for - reverting the `floor > 0` rung to
|
||||
# `excess > 0` - makes `floor_w` None HERE, so a bare `:.0f` raises TypeError
|
||||
# and ABORTS THE WHOLE FILE on the line after the check that just went red.
|
||||
# Parts 2-13 are then ungraded and the recorded coverage of that mutation is
|
||||
# smaller than the truth: exactly what MAINT-05's `delinquent(...)['b']`
|
||||
# subscript did to test_delivery.py, and habit 5 ("a check whose failure mode
|
||||
# is a hang - or a crash - needs a deadline, or a name") in the other costume.
|
||||
print(f" at the boundary: excess {e_edge:.3f} W (an `excess > 0` test would "
|
||||
f"RELEASE: {would_release_on_excess}), floor {released.floor_w:.0f} W "
|
||||
f"RELEASE: {would_release_on_excess}), floor "
|
||||
f"{'(none)' if released.floor_w is None else f'{released.floor_w:.0f} W'} "
|
||||
f"(the shipped `floor > 0` test holds: {released.engaged})")
|
||||
check("...and the claim is held there, not released. `excess` falls to zero as "
|
||||
"soon as the battery is already taking the watts, so thresholding IT is "
|
||||
@@ -5947,6 +5956,281 @@ check("...and the row is green and un-warned, which is what makes the "
|
||||
"operator scrolls past", _rows38[0]["ok"] and not _rows38[0]["warn"]
|
||||
and _S38_CEIL_W - _S38_PROJ.projected_w == 2713.0)
|
||||
|
||||
# ==============================================================================
|
||||
print()
|
||||
print("13. SAFETY-45 - charge_headroom_w(): the number decide() used to throw "
|
||||
"away")
|
||||
# ---------------------------------------------------------------------------
|
||||
# `decide()` computes `wanted = batt_w + excess` - the DISCHARGE that lands the
|
||||
# quarter exactly on the ceiling - and returns `engaged=False, floor_w=None`
|
||||
# the moment that number is not positive. A negative `wanted` is not "nothing
|
||||
# to say": it is a permitted CHARGE of `-wanted` W, and discarding it is what
|
||||
# let an arbitrage charge sit at max_w against a quarter it was blowing.
|
||||
#
|
||||
# ⚠️ NOTHING IN decide() CHANGES IN THIS CARD, AND THAT IS THE POINT. The
|
||||
# `wanted <= 0` branch is 2026-08-20's anti-bang-bang rung and part 6's replay
|
||||
# is what proves it still holds; this part grades a PURE READ of the number it
|
||||
# already carried. 13g asserts the branch is still there rather than trusting
|
||||
# the diff.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _proj_at(net_w, elapsed):
|
||||
return PeakTracker.project(averager_at(net_w, elapsed),
|
||||
B + timedelta(seconds=elapsed))
|
||||
|
||||
|
||||
def _decide_on(projection, *, batt_w, soc=SOC_OK, cap_w=CAP_W,
|
||||
achievable_w=LIVE_MAX_W, reading=None, frozen=False):
|
||||
return decide(projection, batt_w=batt_w, cap_w=cap_w, reading=reading,
|
||||
achievable_w=achievable_w, soc=soc, soc_floor=SOC_FLOOR,
|
||||
max_hold_s=MAX_HOLD_S, frozen=frozen)
|
||||
|
||||
|
||||
def _decide_at(net_w, elapsed, **kw):
|
||||
return _decide_on(_proj_at(net_w, elapsed), **kw)
|
||||
|
||||
|
||||
def _avg_held(base_w, elapsed, held_w, *, start=B, step=5.0):
|
||||
"""`elapsed` seconds BANKED at `base_w`, then `held_w` standing at the edge.
|
||||
|
||||
⚠️ THE HISTORY AND THE HELD VALUE ARE SEPARATE FIXTURE AXES, and 13c is why
|
||||
this helper exists rather than `averager_at(load - batt, ...)`. The averager
|
||||
credits a sample from its own timestamp to the NEXT one, so the last sample
|
||||
contributes ZERO accumulated seconds and only becomes `held`. That is the
|
||||
real shape of a battery whose command changed a moment ago - the quarter's
|
||||
banked seconds do not retroactively change - and a fixture that moved the
|
||||
whole history with it would be grading a different quarter each time.
|
||||
"""
|
||||
a = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
|
||||
t = 0.0
|
||||
while t < elapsed:
|
||||
a.add(sample(start + timedelta(seconds=t), base_w))
|
||||
t += step
|
||||
a.add(sample(start + timedelta(seconds=elapsed), held_w))
|
||||
return a
|
||||
|
||||
|
||||
# --- 13a. the number, and it is DERIVED rather than read back ---------------
|
||||
# The house is flat at 2600 W under a 3500 W cap, the battery is idle, and 300 s
|
||||
# of the block are banked. 600 s remain, so the block can still absorb
|
||||
# 900 W x 900/600 = 1350 W of extra offtake and finish exactly on the ceiling.
|
||||
_H45_GAP = 900.0
|
||||
_H45_LOAD = CAP_W - _H45_GAP
|
||||
_H45_EL, _H45_REM = 300.0, QUARTER_S - 300.0
|
||||
_h45_idle = _decide_at(_H45_LOAD, _H45_EL, batt_w=0.0)
|
||||
_h45_head = charge_headroom_w(_h45_idle)
|
||||
# The CONSEQUENCE, computed from the fixture's own literals and not from the
|
||||
# module's arithmetic: hold that charge for the rest of the block and the
|
||||
# BILLED AVERAGE is the ceiling. This is the meaning of the number, which is a
|
||||
# different statement from the expression that produces it (habit 2).
|
||||
_H45_FINAL = (_H45_LOAD * _H45_EL
|
||||
+ (_H45_LOAD + _h45_head) * _H45_REM) / QUARTER_S
|
||||
print(f" house {_H45_LOAD:.0f} W under a {CAP_W:.0f} W cap, battery 0 W, "
|
||||
f"{_H45_EL:.0f} s banked: engaged={_h45_idle.engaged}, "
|
||||
f"wanted={_h45_idle.wanted_w:+.0f} W, headroom={_h45_head:.0f} W")
|
||||
print(f" holding that charge for the remaining {_H45_REM:.0f} s bills the "
|
||||
f"block at {_H45_FINAL:.1f} W against a {CAP_W:.0f} W ceiling")
|
||||
check("the guard files NOTHING here - this is the shipped `wanted <= 0` branch, "
|
||||
"untouched, and the state SAFETY-45 is about",
|
||||
not _h45_idle.engaged and _h45_idle.floor_w is None
|
||||
and _h45_idle.wanted_w is not None and _h45_idle.wanted_w < 0.0)
|
||||
check(f"...and yet the quarter can afford {_h45_head:.0f} W of charging, which "
|
||||
f"is the number that was being discarded. Graded by its CONSEQUENCE - "
|
||||
f"the block lands on the ceiling to the watt - rather than by "
|
||||
f"re-deriving -wanted_w with the module's own formula",
|
||||
near(_H45_FINAL, CAP_W, 0.5))
|
||||
check(f"...and it is none of the other numbers this fixture has: not the cap "
|
||||
f"({CAP_W:.0f}), not max_w ({LIVE_MAX_W:.0f}), not the house "
|
||||
f"({_H45_LOAD:.0f}) and not the raw gap under the ceiling "
|
||||
f"({_H45_GAP:.0f}) - the 900/remaining gain is 1.5 here and a check that "
|
||||
f"could not tell those apart would be decoration",
|
||||
not any(near(_h45_head, v, 1.0)
|
||||
for v in (CAP_W, LIVE_MAX_W, _H45_LOAD, _H45_GAP)))
|
||||
|
||||
# --- 13a2. AND THE IDENTITY HOLDS ACROSS THE WHOLE BLOCK --------------------
|
||||
# ⚠️ THE AMPLIFICATION IS REAL AND IT IS REPORTED WITH ITS SIZE (habit 13).
|
||||
# 900/remaining reaches 180 in the last five seconds, so the headroom there is
|
||||
# enormous - and it is bounded in EFFECT, not in magnitude: at every elapsed,
|
||||
# holding it bills the block at exactly the ceiling.
|
||||
H45_ID = []
|
||||
for _el in (0.0, 60.0, 300.0, 600.0, 870.0, 895.0):
|
||||
_rem = QUARTER_S - _el
|
||||
_hd = charge_headroom_w(_decide_at(_H45_LOAD, _el, batt_w=0.0))
|
||||
H45_ID.append((_el, _hd,
|
||||
(_H45_LOAD * _el + (_H45_LOAD + _hd) * _rem) / QUARTER_S))
|
||||
print(" headroom across the block (elapsed, headroom W, billed W): "
|
||||
+ ", ".join(f"({a:.0f}, {b:.0f}, {c:.1f})" for a, b, c in H45_ID))
|
||||
check("at EVERY point in the block, holding the headroom for the rest of it "
|
||||
"bills the block at exactly the ceiling - so the 162 kW answer five "
|
||||
"seconds from the boundary and the 900 W answer at the top of it are the "
|
||||
"same statement about the bill",
|
||||
all(near(c, CAP_W, 0.5) for _, _, c in H45_ID))
|
||||
check("...and the fixture SPANS the amplification rather than sitting in one "
|
||||
f"corner of it: the headroom moves by a factor of "
|
||||
f"{max(b for _, b, _ in H45_ID) / min(b for _, b, _ in H45_ID):.0f} "
|
||||
f"across those six points",
|
||||
max(b for _, b, _ in H45_ID) > 100.0 * min(b for _, b, _ in H45_ID))
|
||||
|
||||
# --- 13b. HOLDING implies ZERO OR UNKNOWN, swept - the family, not one case -
|
||||
# ⚠️ THE PROPERTY THAT MAKES THIS SAFE TO HAND A STRATEGY. Every state that
|
||||
# files a claim has `wanted > 0`, `wanted is None` or `blind`, so this function
|
||||
# can never hand a caller permission the guard's own `lo` is at that instant
|
||||
# refusing. Swept over the same grid part 5's no-negative-floor proof uses,
|
||||
# widened with the two ways a cycle can fail to measure at all.
|
||||
H45_N = H45_BAD = H45_POS = H45_NONE = H45_ZERO = 0
|
||||
for _load in (0.0, CAP_W - 500.0, CAP_W, CAP_W + 300.0, CAP_W + 3000.0,
|
||||
LIVE_MAX_W * 3):
|
||||
for _el in (30.0, 450.0, 870.0):
|
||||
for _bw in (-LIVE_MAX_W, -2000.0, 0.0, 400.0, 4000.0, None):
|
||||
for _sc in (None, BMS_FLOOR, SOC_FLOOR, SOC_FLOOR + 0.5, 100.0):
|
||||
for _fz in (False, True):
|
||||
_d45 = _decide_at(_load, _el, batt_w=_bw, soc=_sc,
|
||||
frozen=_fz)
|
||||
_hr = charge_headroom_w(_d45)
|
||||
H45_N += 1
|
||||
if _hr is None:
|
||||
H45_NONE += 1
|
||||
elif _hr > 0.0:
|
||||
H45_POS += 1
|
||||
else:
|
||||
H45_ZERO += 1
|
||||
if _d45.engaged and _hr not in (None, 0.0):
|
||||
H45_BAD += 1
|
||||
print(f" swept {H45_N} (load x elapsed x battery x SoC x frozen) "
|
||||
f"combinations: {H45_BAD} ENGAGED decisions answering a positive "
|
||||
f"headroom; {H45_POS} permit charging, {H45_ZERO} answer 0 W, "
|
||||
f"{H45_NONE} unmeasured")
|
||||
check(f"NOT ONE of the {H45_N} combinations answers a positive headroom while "
|
||||
f"the guard is ENGAGED. A decision whose `lo` is at that instant "
|
||||
f"forbidding charging can never be read as permission to charge",
|
||||
H45_BAD == 0 and H45_N > 800)
|
||||
check("...and the sweep is vacuous in no direction: it reaches decisions that "
|
||||
f"permit charging ({H45_POS}), decisions that permit none ({H45_ZERO}) "
|
||||
f"and decisions nothing measured ({H45_NONE}), so all three answers are "
|
||||
f"exercised", H45_POS > 0 and H45_ZERO > 0 and H45_NONE > 0)
|
||||
|
||||
# --- 13c. IT IS INVARIANT IN THE BATTERY, WHICH IS WHY SIZING A TRADE TO IT
|
||||
# CANNOT OSCILLATE -------------------------------------------------
|
||||
# Raise the charge by dW and the METER rises by dW, so `excess` rises by exactly
|
||||
# dW while `batt_w` falls by dW: `wanted` does not move. The headroom is a
|
||||
# FEED-FORWARD number - a function of the house, the ceiling and the seconds
|
||||
# already banked - so consuming it adds no feedback path around the plant.
|
||||
# Without this property the whole fix would be one loop replacing another.
|
||||
H45_INV, H45_EX = [], []
|
||||
for _bw in (-LIVE_MAX_W, -2000.0, -500.0, 0.0, 500.0, 2000.0):
|
||||
# ONE banked history, and the battery's change visible only in the HELD
|
||||
# value - which is what a command given a moment ago actually looks like.
|
||||
_d = _decide_on(PeakTracker.project(
|
||||
_avg_held(_H45_LOAD, _H45_EL, _H45_LOAD - _bw),
|
||||
B + timedelta(seconds=_H45_EL)), batt_w=_bw)
|
||||
H45_INV.append(charge_headroom_w(_d))
|
||||
H45_EX.append(round(_d.excess_w, 1))
|
||||
print(f" same house, same banked quarter, battery {-LIVE_MAX_W:+.0f}.."
|
||||
f"{2000.0:+.0f} W: headroom {[round(v, 3) for v in H45_INV]}")
|
||||
print(f" ...while the EXCESS those runs see is {H45_EX}")
|
||||
check("the headroom does NOT move when the battery moves across the whole "
|
||||
"range of what it can do - it is a property of the HOUSE and the "
|
||||
"CEILING, not of what the battery happens to be doing, which is what "
|
||||
"makes a trade sized from it feed-forward rather than a second loop "
|
||||
"around the plant",
|
||||
max(H45_INV) - min(H45_INV) < 1.0)
|
||||
check(f"...and the fixture SEPARATES it from the two quantities it is built "
|
||||
f"out of: the battery moved {LIVE_MAX_W + 2000.0:.0f} W and the excess "
|
||||
f"with it, over {len(set(H45_EX))} distinct values, so an implementation "
|
||||
f"answering `-batt_w` or `abs(excess)` would give six different answers "
|
||||
f"here (habit 4)",
|
||||
len(set(H45_EX)) == len(H45_EX)
|
||||
and len(set(round(v, 3) for v in H45_INV)) == 1)
|
||||
|
||||
# --- 13d. AND A BOUNDARY HANDS IT BACK AT THE AFFORDABLE RATE, NOT AT max_w --
|
||||
# ⚠️ SAFETY-45's SECOND HALF, AND THE CLAIM IS NOT "IT DOES NOT CHANGE".
|
||||
# `project()` resets to the held level at `elapsed = 0`, and the headroom
|
||||
# collapses with it - from 162 kW to 900 W here. What the card is about is WHAT
|
||||
# IT COLLAPSES TO: the house and the cap, and nothing else. The behaviour being
|
||||
# removed re-armed at `max_w` regardless of either.
|
||||
_H45_END = charge_headroom_w(_decide_at(_H45_LOAD, 895.0, batt_w=0.0))
|
||||
_H45_TOP = charge_headroom_w(_decide_at(_H45_LOAD, 0.0, batt_w=0.0))
|
||||
print(f" across a boundary, same house: {_H45_END:.0f} W with 5 s of the "
|
||||
f"old quarter left -> {_H45_TOP:.0f} W with the new one 0 s old, against "
|
||||
f"a max_w of {LIVE_MAX_W:.0f} W")
|
||||
check(f"at the top of the new quarter the headroom is exactly the ceiling less "
|
||||
f"the house ({CAP_W:.0f} - {_H45_LOAD:.0f} = {_H45_GAP:.0f} W). A trade "
|
||||
f"refused at 14:59 resumes at 15:00 at the rate the new quarter can "
|
||||
f"afford - the projection resets, this does not reset TO max_w",
|
||||
near(_H45_TOP, _H45_GAP, 1.0) and _H45_TOP < LIVE_MAX_W)
|
||||
check("...and the check is not passing because nothing moved: the headroom on "
|
||||
"the other side of that boundary is two orders of magnitude larger, and "
|
||||
"the PROJECTION really did reset",
|
||||
_H45_END > 100.0 * _H45_TOP and _proj_at(_H45_LOAD, 0.0).elapsed_s < 1.0)
|
||||
|
||||
# --- 13e. the unmeasured answers, and None is NOT unlimited -----------------
|
||||
_h45_nobatt = _decide_at(_H45_LOAD, _H45_EL, batt_w=None)
|
||||
_h45_blind = _decide_at(_H45_LOAD, _H45_EL, batt_w=0.0, frozen=True)
|
||||
print(f" no battery reading: {charge_headroom_w(_h45_nobatt)}; "
|
||||
f"BLIND: {charge_headroom_w(_h45_blind)}; no decision at all: "
|
||||
f"{charge_headroom_w(None)}")
|
||||
check("a guard that never ran answers None, not a number - `meter_source: off` "
|
||||
"reaches this with no decision at all and a caller that read it as a "
|
||||
"large headroom would be guard_state()'s None-is-not-False collapse one "
|
||||
"layer down", charge_headroom_w(None) is None)
|
||||
check("...and a cycle with NO BATTERY MEASUREMENT answers None too: there is "
|
||||
"nothing to size a floor from, so there is nothing to size a trade from "
|
||||
"either", charge_headroom_w(_h45_nobatt) is None
|
||||
and _h45_nobatt.wanted_w is None)
|
||||
check("...and BLIND answers 0.0 - a NUMBER, and the number is no charging. "
|
||||
"The claim it files already says exactly that at `floor 0 W`, and this "
|
||||
"agrees with it rather than restating it",
|
||||
charge_headroom_w(_h45_blind) == 0.0 and _h45_blind.blind
|
||||
and _h45_blind.floor_w == 0.0)
|
||||
check("...and the three are TOLD APART: blind is 0.0 and the two unmeasured "
|
||||
"states are None, so a caller can refuse for the reason that is true "
|
||||
"rather than for whichever fired first",
|
||||
charge_headroom_w(_h45_blind) is not None
|
||||
and charge_headroom_w(_h45_nobatt) is None)
|
||||
|
||||
# --- 13f. the SoC floor does not become charging permission -----------------
|
||||
# ⚠️ THE ONE ENGAGED STATE WHERE THE GUARD IS DELIBERATELY NOT DISCHARGING.
|
||||
# SAFETY-24's floor-limited decision files `lo = 0.0` - "charging stays
|
||||
# blocked" - on a quarter that IS over the ceiling. If that read as headroom,
|
||||
# an empty pack in a blown quarter would be told to buy.
|
||||
_h45_lim = _decide_at(CAP_W + 2000.0, _H45_EL, batt_w=0.0, soc=SOC_FLOOR - 1.0)
|
||||
print(f" floor-limited over a blown quarter: engaged={_h45_lim.engaged}, "
|
||||
f"floor_limited={_h45_lim.floor_limited}, wanted="
|
||||
f"{_h45_lim.wanted_w:+.0f} W, headroom={charge_headroom_w(_h45_lim)}")
|
||||
check("a FLOOR-LIMITED decision - the guard wanted a discharge and SoC refused "
|
||||
"to size it - answers 0.0 headroom. The quarter is over the ceiling; the "
|
||||
"pack being empty is not a reason to fill it from the grid in it",
|
||||
_h45_lim.floor_limited and _h45_lim.engaged
|
||||
and charge_headroom_w(_h45_lim) == 0.0)
|
||||
|
||||
# --- 13g. decide() ITSELF IS UNCHANGED, PINNED -----------------------------
|
||||
# ⚠️ MUTATION.md habit 4, in the direction a diff cannot cover. The whole safety
|
||||
# argument of this card is "the 2026-08-20 rung is still there and part 6 still
|
||||
# grades it". That is a claim about the SOURCE, so it is pinned on the source -
|
||||
# and on the BEHAVIOUR, because a shape pin alone would pass a rung that had
|
||||
# been inverted.
|
||||
_H45_SRC = (HERE / "app" / "peakguard.py").read_text(encoding="utf-8")
|
||||
_H45_TREE = ast.parse(_H45_SRC)
|
||||
_h45_fn = next(n for n in ast.walk(_H45_TREE)
|
||||
if isinstance(n, ast.FunctionDef) and n.name == "decide")
|
||||
_H45_RUNG = [n for n in ast.walk(_h45_fn) if isinstance(n, ast.If)
|
||||
and ast.unparse(n.test) == "wanted <= 0.0"]
|
||||
check("the `wanted <= 0.0` rung is still in decide(), spelled exactly that "
|
||||
"way, on the AST rather than as a substring - it is the rung whose "
|
||||
"removal put 2026-08-20's quarter 49 W over the limit after seventeen "
|
||||
"engage/release cycles in 900 s", len(_H45_RUNG) == 1)
|
||||
check("...and it still DISENGAGES rather than merely reporting: the fixture "
|
||||
"13a is built on reaches it and files no claim, so the pin above is not "
|
||||
"grading a rung that has been inverted under it",
|
||||
peakguard.claim(_h45_idle) is None)
|
||||
_h45_head_fn = next(n for n in _H45_TREE.body if isinstance(n, ast.FunctionDef)
|
||||
and n.name == "charge_headroom_w")
|
||||
check("...and charge_headroom_w() is a PURE READ of the decision - one "
|
||||
"positional parameter, no projection, no clock and no options - so it "
|
||||
"cannot become a second answer to the question decide() already answers",
|
||||
[a.arg for a in _h45_head_fn.args.args] == ["decision"]
|
||||
and not _h45_head_fn.args.kwonlyargs)
|
||||
|
||||
# ==============================================================================
|
||||
print()
|
||||
shutil.rmtree(TMP, ignore_errors=True)
|
||||
|
||||
@@ -21,6 +21,7 @@ from app.maintenance import MAINT_OPTION_DEFAULTS, MaintConfig
|
||||
from app.price import (
|
||||
PRICE_OPTION_DEFAULTS, SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
|
||||
from app.control import LOOP_TICK_S, PLANT_SETTLE_S, SLEW_RAIL_FRAC
|
||||
from app import shadow
|
||||
from app.validate import (
|
||||
ACTUATOR_WRITE_KEYS, FIRMWARE_INGEST_VETO_S, ConfigRefused,
|
||||
actuator_writers, refuse, site_rail_w, validate_startup_config,
|
||||
@@ -1722,6 +1723,90 @@ check("and the 6% asymmetry is reported as an ORDERED PAIR: the transposed "
|
||||
"vat_pct 6" not in _T16_PAIR[0])
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
print("\nSAFETY-10 - shadow_mode is validated like every other option")
|
||||
# ⚠️ WHY THIS IS A REFUSAL AND NOT A COERCION. `shadow.mode()` resolves an
|
||||
# unrecognised value to SHADOW - the direction that does not move energy - and
|
||||
# an install silently reinterpreted that way COMMANDS NOTHING, indefinitely,
|
||||
# while its status page calmly explains that this is intentional. A typo is not
|
||||
# a decision, and UX-02 made this validator the one rule surface both editors
|
||||
# read, so the rule has to be here rather than in a quiet fallback.
|
||||
_S10_BAD = ["true", "yes", "1", "shadow", "", "autoo", None, 1]
|
||||
for _v in _S10_BAD:
|
||||
_p = validate_startup_config(base(shadow_mode=_v), -5000, 5000)
|
||||
check(f"shadow_mode={_v!r} is REFUSED, and the refusal SPELLS the key so "
|
||||
"configui.problems_by_field() can file it under the right control",
|
||||
why(_p, "shadow_mode is") and why(_p, "'auto'")
|
||||
and why(_p, "'on'") and why(_p, "'off'"))
|
||||
for _v in ("auto", "on", "off", "AUTO", " on ", "Auto "):
|
||||
check(f"shadow_mode={_v!r} starts - the three values and the tolerant "
|
||||
"spellings of them are accepted, so the rule above refuses garbage "
|
||||
"and not case",
|
||||
validate_startup_config(base(shadow_mode=_v), -5000, 5000) == [])
|
||||
check("PRECONDITION: and the key being ABSENT starts too, which is what every "
|
||||
"install that upgrades into this version has. A rule that refused the "
|
||||
"absent key would refuse every existing install at once",
|
||||
validate_startup_config(base(), -5000, 5000) == []
|
||||
and "shadow_mode" not in base())
|
||||
# The two arrangements have to DISAGREE somewhere, or `why()` is grading a
|
||||
# sentence that is in the list for another reason entirely.
|
||||
check("...and a refused shadow_mode is the ONLY thing wrong with that config, "
|
||||
"so the refusal above is this rule's and not some other rule's",
|
||||
len(validate_startup_config(base(shadow_mode="maybe"), -5000, 5000)) == 1)
|
||||
|
||||
|
||||
# --- THE SIX STATES, AND THE ONE THAT PROTECTS THE EXISTING INSTALL ---------
|
||||
# ⚠️ GRADED HERE RATHER THAN IN test_clamp.py, WHERE IT STARTED, AND THE REASON
|
||||
# IS MEASURED. `shadow.engaged()` is a pure function of the option and the
|
||||
# start button; a mutation that defeats the DEFAULT stops test_clamp.py's
|
||||
# part 3 reaching the wire at all, which aborts that file with an IndexError
|
||||
# before part 8 runs - so the mutation's red count there is a lower bound and
|
||||
# the table itself is never graded (MUTATION.md, FCST-06's shape). Nothing in
|
||||
# this file drives a Controller, so nothing here can be taken down that way.
|
||||
# Six states. The one that matters most is the LAST row: an install that is
|
||||
# controlling today must not be changed by this option arriving with a default.
|
||||
_TABLE = [
|
||||
("off", True, False), ("off", False, False),
|
||||
("on", True, True), ("on", False, True),
|
||||
("auto", False, True), ("auto", True, False),
|
||||
]
|
||||
for _m, _started, _want in _TABLE:
|
||||
check(f"shadow_mode {_m!r} with control "
|
||||
f"{'started' if _started else 'stopped'} -> "
|
||||
f"{'SHADOW' if _want else 'LIVE'}",
|
||||
shadow.engaged({"shadow_mode": _m}, control_started=_started)
|
||||
is _want)
|
||||
check("THE EXISTING INSTALL: the SHIPPED DEFAULT, on an install that is "
|
||||
"controlling, is LIVE. This is the whole reason the option is not a "
|
||||
"boolean defaulting to true - the Supervisor merges a new default into "
|
||||
"every existing install, and a boolean would have stopped a battery that "
|
||||
"is regulating a real house today",
|
||||
shadow.engaged({}, control_started=True) is False)
|
||||
check("...and the SAME shipped default on a FRESH install - `auto_start` is "
|
||||
"false, so nothing has started - is SHADOW. That is what 'default-on' "
|
||||
"means here, delivered where it is safe",
|
||||
shadow.engaged({}, control_started=False) is True)
|
||||
# ⚠️ THE REASON, NOT THE VERDICT (MUTATION.md's masking rule). `on` and
|
||||
# `auto`-while-stopped are the same boolean and want DIFFERENT operator
|
||||
# actions: one is an option, the other is a button. A surface showing only the
|
||||
# verdict would be blind to the two rungs being swapped.
|
||||
check("the two ways of being in shadow mode are told apart in words, so a "
|
||||
"build that swapped the rungs could not render identically",
|
||||
shadow.why({"shadow_mode": "on"}, control_started=False)
|
||||
!= shadow.why({"shadow_mode": "auto"}, control_started=False))
|
||||
|
||||
# ⚠️ AND THE FAIL-SAFE DIRECTION OF AN UNREADABLE VALUE IS GRADED, THOUGH THE
|
||||
# rule above means a running install can never hold one. It survived the first
|
||||
# mutation battery as M9 for exactly that reason: everything else refused the
|
||||
# value before `mode()` ever saw it, so the direction it fails in was ungraded
|
||||
# and could have been flipped to "live" with the whole suite green.
|
||||
check("an UNREADABLE shadow_mode resolves to SHADOW, not to live - the "
|
||||
"direction that does not move energy. It is reachable only if this "
|
||||
"file's rule is ever weakened, which is the case it exists for",
|
||||
shadow.engaged({"shadow_mode": "garbage"}, control_started=True) is True
|
||||
and shadow.engaged({"shadow_mode": ""}, control_started=True) is True
|
||||
and shadow.mode({"shadow_mode": "garbage"}) == "on")
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
print()
|
||||
if fails:
|
||||
|
||||
@@ -2858,6 +2858,115 @@ check("...and the SITE sign detector is still absent at a roster of one - part "
|
||||
not _c38one.site_sign_wd.tripped
|
||||
and _c38one.site_sign_wd.disagree_since is None)
|
||||
|
||||
# =========================================================================== #
|
||||
# 10. SAFETY-10 - THE SIGN WATCHDOG IN SHADOW MODE
|
||||
# =========================================================================== #
|
||||
# THE QUESTION THE CARD ASKS OF EVERY FAILSAFE: does it observe, does it latch,
|
||||
# or is it inert in shadow mode? For this one the answer had to be INERT, and
|
||||
# the reason is the worst outcome in the feature:
|
||||
#
|
||||
# SAFETY-02 grades the command STANDING ON THE WIRE against the meter. Shadow
|
||||
# mode holds the wire at 0 W, so the detector cannot arm. Fed the SHADOW
|
||||
# DECISION instead it would compare a number against a meter that never saw
|
||||
# it - guaranteed disagreement for as long as the decision asked for power -
|
||||
# and TRIP. That latch survives into live operation AND across a restart
|
||||
# (part 3 of this file is that property), so a shadow run would hand the
|
||||
# operator a battery that will not move, from a run in which nothing moved.
|
||||
# Shadow mode would manufacture the failsafe it exists to help debug.
|
||||
#
|
||||
# ⚠️ GRADED ON THE SAME STIMULUS THAT TRIPS IT LIVE, NOT ON A QUIET ONE.
|
||||
# MUTATION.md: a per-thing check that has never seen the things DISAGREE is a
|
||||
# total. `_s10_sign()` is `_e2e()` above with one option changed - the same
|
||||
# inverted loop, the same steady 2000 W import, the same 1 s window.
|
||||
print("\n10. SAFETY-10 - the sign watchdog in shadow mode\n")
|
||||
|
||||
|
||||
async def _s10_sign(shadow_mode):
|
||||
hass = _Hass()
|
||||
opts = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
|
||||
"soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
|
||||
"meter_source": "off", "max_w": 2000, "gain": -0.6,
|
||||
"sign_disagree_w": 300, "sign_disagree_s": 1, "auto_start": True,
|
||||
# ⚠️ AN EXPLICIT SLEW, AND THE REASON IS THE LIMITATION GRADED
|
||||
# BELOW. At `slew_w: 0` the rail is `max_w / 9` = 222 W, and in
|
||||
# shadow mode the loop starts from the 0 W standing on the wire
|
||||
# EVERY cycle - so its decision never leaves 222 W and never
|
||||
# reaches the 300 W gate at all. The detector would then be
|
||||
# "inert" for a reason that has nothing to do with this card.
|
||||
"slew_w": 1000,
|
||||
"shadow_mode": shadow_mode}
|
||||
c = Controller(opts, hass, _S(), _P(), stop=asyncio.Event())
|
||||
c.auto = True
|
||||
c.dev_min, c.dev_max = -5000.0, 5000.0
|
||||
wanted = []
|
||||
for _ in range(12):
|
||||
await c.read_inputs()
|
||||
await c.cycle()
|
||||
wanted.append(c.shadow_would_w if c.shadow else c.target)
|
||||
await asyncio.sleep(0.25)
|
||||
return c, hass, wanted
|
||||
|
||||
|
||||
_s10_live, _s10_lh, _s10_lw = asyncio.run(_s10_sign("off"))
|
||||
_s10_shad, _s10_sh, _s10_sw = asyncio.run(_s10_sign("on"))
|
||||
print(f" live : tripped={_s10_live.sign_wd.tripped} "
|
||||
f"wanted={[round(w) for w in _s10_lw[:4]]}")
|
||||
print(f" shadow: tripped={_s10_shad.sign_wd.tripped} "
|
||||
f"wanted={[round(w) for w in _s10_sw[:4]]}")
|
||||
check("PRECONDITION: the same stimulus TRIPS the watchdog with shadow mode "
|
||||
"off, so what follows is a claim about shadow mode and not about a "
|
||||
"stimulus that could never have tripped anything",
|
||||
_s10_live.sign_wd.tripped)
|
||||
check("PRECONDITION: and in shadow mode the decision path still asked for "
|
||||
"charge into that import - well past the 300 W gate - so the detector "
|
||||
"had a wrong-way number available to it and did not use it",
|
||||
any(w is not None and w < -300.0 for w in _s10_sw))
|
||||
check("SAFETY-10: the sign watchdog is INERT in shadow mode. It grades what "
|
||||
"this controller has standing on the wire, and that is 0 W - so a latch "
|
||||
"that would survive into live operation and across a restart is never "
|
||||
"armed by a run in which nothing was commanded",
|
||||
not _s10_shad.sign_wd.tripped
|
||||
and _s10_shad.sign_wd.disagree_since is None)
|
||||
check("...and it is inert BY CONSTRUCTION, not by a special case: the value it "
|
||||
"was handed is `Inverter.standing_w()`, which is the 0 W shadow mode "
|
||||
"actually wrote and not the decision it recorded",
|
||||
_s10_shad.inverters[0].standing_w() == 0.0
|
||||
and set(_s10_sh.writes) == {0.0})
|
||||
# ⚠️ AND THE LIMITATION IS RECORDED HERE RATHER THAN LEFT FOR SOMEBODY TO
|
||||
# DISCOVER. `_shadow_settle()` re-seeds the loop's `prev_w` to what is standing
|
||||
# on the wire, so in shadow mode the loop leg answers "what would this
|
||||
# controller command NOW, from a battery at 0 W" - ONE STEP - and not "what
|
||||
# trajectory would it have followed". The trajectory is a closed-loop property
|
||||
# and it did not happen; reporting it would be a simulation of a plant that
|
||||
# does not exist. The strategies are unaffected: arbitrage, the peak guard and
|
||||
# maintenance all file SET claims at a fixed power from level-triggered inputs,
|
||||
# which is why the three defects this card was written for are all visible from
|
||||
# a shadow run and this one is not.
|
||||
check("RECORDED LIMITATION: the loop leg's shadow decision is ONE slew step "
|
||||
"from the standing command and stays there, while the live run RAMPS. A "
|
||||
"shadow run answers 'what would it do now', not 'what trajectory would "
|
||||
f"it have followed' (shadow {[round(w) for w in _s10_sw[:4]]} vs live "
|
||||
f"{[round(w) for w in _s10_lw[:4]]})",
|
||||
len({round(w) for w in _s10_sw if w is not None}) == 1
|
||||
and len({round(w) for w in _s10_lw[:4]}) > 1)
|
||||
# ⚠️ AND "INERT" HAD TO BE SHOWN TO MEAN STARVED, NOT DISABLED. A detector
|
||||
# that had been switched off would satisfy every check above and would still
|
||||
# be off the moment shadow mode ends. So the SAME object, off the SAME
|
||||
# controller, is handed the disagreement the run never let it see.
|
||||
_s10_n0 = datetime.now(timezone.utc)
|
||||
_s10_wd = _s10_shad.inverters[0].sign_wd
|
||||
check("PRECONDITION: it is not tripped going in, so what follows is this "
|
||||
"stimulus and not a latch left over from the run",
|
||||
not _s10_wd.tripped)
|
||||
_s10_wd.evaluate(-1500.0, 2000.0, True, _s10_n0)
|
||||
_s10_fired = _s10_wd.evaluate(-1500.0, 2000.0, True,
|
||||
_s10_n0 + timedelta(seconds=5))
|
||||
check("...and the failsafe is STARVED, not DISABLED: handed -1500 W standing "
|
||||
"against a +2000 W import - the evidence shadow mode never lets it see - "
|
||||
"the very same detector object trips. It is armed for the moment shadow "
|
||||
"mode ends",
|
||||
bool(_s10_fired) and _s10_wd.tripped)
|
||||
|
||||
print()
|
||||
if fails:
|
||||
print(f"{len(fails)} FAILED: {', '.join(fails)}")
|
||||
|
||||
@@ -249,6 +249,9 @@ configuration:
|
||||
delivery_hold_s:
|
||||
name: "Safety · Not-delivering report after (s) — derived, do not change"
|
||||
description: "TWO OR MORE INVERTERS ONLY; with one inverter this check cannot fire at all, and that is deliberate rather than a limitation. How long ONE inverter may stand at a discharge share it is not producing - short by more than the saturation threshold, with nothing this add-on can read to explain it - while at least one sibling is NOT in that state, before it is named. REPORTS ONLY (SAFETY-42): nothing is commanded differently, the loop is untouched, and the site goes on running short by that unit's share until you look. DERIVED FROM 2640 CLOSED-LOOP TEST RUNS in which nothing was faulty (SAFETY-42, plus a one-inverter arm as the control, which reports nothing at any threshold): the worst legitimate episode those runs produce is 35.0 s, and the ceiling is the 900 s quarter that bills the capacity tariff. 185 s is 5.29 times that. ⚠️ The schema lets you set this as low as 30 s, which is BELOW that measured 35.0 s - at 30 s you should expect reports on legitimate saturation. The second inverter in those tests is a COPY OF THE FIRST, because the second inverter does not exist yet: what a unit four times slower would produce (75.0 s) is a sensitivity study on that idea, not a measurement of any real second inverter. Do not change it without re-deriving it - and it can be re-derived now: admin/goodwe sim/delivery_window.py --campaign --blag (TEST-21). A pack at or below its own bms_soc_floor is never reported: an empty pack and a wedged one are identical watt for watt, and that setting is the only thing that tells them apart - so if this fires on a pack you believe is empty, that setting does not describe your battery."
|
||||
shadow_mode:
|
||||
name: "Safety · Shadow mode — run every decision, command nothing"
|
||||
description: "Runs the whole decision path — strategies, arbiter, clamps and guards — and sends NOTHING to the inverter. Every inverter is held at 0 W, refreshed on the ordinary heartbeat, and the status page says plainly that the battery is not being controlled; the decision it WOULD have commanded, and why, is on the status page and in the action log. This is how you watch a site for a day before letting it trade. 'auto' (the shipped value) means shadow mode while control is stopped and ordinary control once you press Start — so a NEW install observes before it ever commands anything, and an install that is already controlling is not changed by one watt. 'on' means shadow mode always, whatever the Start / stop button says: that is the setting to pick when you want the loop and the strategies running on a live site with nothing reaching the battery. 'off' is ordinary control. ⚠️ While this is on the battery is NOT being regulated — the grid is not held at zero, no arbitrage trade is executed and no capacity peak is shaved. ⚠️ A failsafe latch that was already up stays up: shadow mode does not clear it, and the banner names it."
|
||||
auto_start:
|
||||
name: "Advanced · Start controlling automatically on boot"
|
||||
description: "Off by default. Leave it off until the site has been commissioned: with it off, somebody has to press Start after every restart of the add-on, which is what you want while you are still checking signs and entities."
|
||||
|
||||
@@ -229,6 +229,9 @@ configuration:
|
||||
delivery_hold_s:
|
||||
name: "Veiligheid · Melding niet-leverende omvormer na (s) — afgeleid, niet wijzigen"
|
||||
description: "ALLEEN BIJ TWEE OF MEER OMVORMERS; bij één omvormer kan deze controle helemaal niet aanslaan, en dat is een bewuste keuze en geen tekortkoming. Hoe lang één omvormer mag blijven staan op een ontlaadaandeel dat hij niet levert - meer dan de verzadigingsdrempel te weinig, zonder dat deze add-on er een verklaring voor kan uitlezen - terwijl minstens één andere omvormer dat NIET doet, voordat hij bij naam wordt gemeld. ALLEEN MELDEN (SAFETY-42): er wordt niets anders gestuurd, de regeling blijft ongemoeid, en de installatie blijft draaien met het aandeel van die omvormer te weinig tot u gaat kijken. AFGELEID UIT 2640 GESLOTEN-LUSTESTS waarbij niets defect was (SAFETY-42, plus een arm met één omvormer als controlegroep, die bij geen enkele drempel iets meldt): de langste terechte episode in die tests duurt 35,0 s, en de bovengrens is het factuurkwartier van 900 s. 185 s is 5,29 keer zoveel. ⚠️ Het schema laat u zo laag als 30 s instellen, en dat is ONDER die gemeten 35,0 s - op 30 s moet u meldingen bij terechte verzadiging verwachten. De tweede omvormer in die tests is een KOPIE VAN DE EERSTE, want de tweede omvormer bestaat nog niet: wat een vier keer tragere eenheid zou opleveren (75,0 s) is een gevoeligheidsstudie op dat idee en geen meting aan een echte tweede omvormer. Verander dit niet zonder de afleiding opnieuw te maken - en dat kan nu: admin/goodwe sim/delivery_window.py --campaign --blag (TEST-21). Een accu op of onder zijn eigen bms_soc_floor wordt nooit gemeld: een lege accu en een vastgelopen omvormer zijn watt voor watt identiek, en die instelling is het enige wat ze uit elkaar houdt - slaat dit toch aan bij een accu die volgens u leeg is, dan beschrijft die instelling uw batterij niet."
|
||||
shadow_mode:
|
||||
name: "Veiligheid · Schaduwmodus — alles beslissen, niets sturen"
|
||||
description: "Doorloopt het volledige beslispad — strategieën, arbiter, begrenzers en bewakingen — en stuurt NIETS naar de omvormer. Elke omvormer wordt op 0 W gehouden, ververst op de gewone hartslag, en de statuspagina zegt onomwonden dat de batterij niet wordt aangestuurd; wat er gestuurd ZOU zijn, en waarom, staat op de statuspagina en in het actielogboek. Zo bekijkt u een installatie een dag lang voordat u hem laat handelen. 'auto' (de meegeleverde waarde) betekent schaduwmodus zolang de regeling gestopt is en gewone regeling zodra u op Start drukt — een NIEUWE installatie kijkt dus eerst toe voordat ze ooit iets stuurt, en een installatie die al regelt verandert geen watt. 'on' betekent altijd schaduwmodus, wat de Start/stop-knop ook zegt: die stand kiest u als u de lus en de strategieën wilt laten draaien op een werkende installatie zonder dat er iets bij de batterij aankomt. 'off' is gewone regeling. ⚠️ Zolang dit aanstaat wordt de batterij NIET geregeld — het net wordt niet op nul gehouden, er wordt geen prijshandel uitgevoerd en er wordt geen capaciteitspiek afgevlakt. ⚠️ Een vergrendeling die al aanstond blijft aanstaan: schaduwmodus heft die niet op, en de banner noemt hem."
|
||||
auto_start:
|
||||
name: "Geavanceerd · Automatisch beginnen te regelen bij opstarten"
|
||||
description: "Staat standaard uit. Laat het uit tot de installatie in dienst is genomen: zolang het uit staat, moet iemand na elke herstart van de add-on op Start drukken, en dat is precies wat u wilt terwijl u tekens en entiteiten nog aan het nakijken bent."
|
||||
|
||||
Reference in New Issue
Block a user