Merge pull request #29 from m4r1k/feat/voltage-grid-quality-reporting

feat(voltage): grid-quality reporting (clamp + severity bypass) — rc9

Author: m4r1k

README.md

@@ -4,12 +4,12 @@
 
 **UPS monitoring and shutdown orchestration for NUT**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![NUT Compatible](https://img.shields.io/badge/NUT-compatible-green.svg)](https://networkupstools.org/)
-[![codecov](https://codecov.io/gh/m4r1k/Eneru/branch/main/graph/badge.svg)](https://codecov.io/gh/m4r1k/Eneru)
-[![Documentation](https://img.shields.io/badge/docs-Read%20The%20Docs-blue.svg)](https://eneru.readthedocs.io/)
-[![PyPI](https://img.shields.io/pypi/v/eneru.svg)](https://pypi.org/project/eneru/)
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-e8e8ed?style=for-the-badge&labelColor=090909" alt="MIT"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.9+-e8e8ed?style=for-the-badge&labelColor=090909" alt="Python 3.9+"></a>
+<a href="https://networkupstools.org/"><img src="https://img.shields.io/badge/NUT-compatible-e8e8ed?style=for-the-badge&labelColor=090909" alt="NUT compatible"></a>
+<a href="https://codecov.io/gh/m4r1k/Eneru"><img src="https://img.shields.io/codecov/c/github/m4r1k/Eneru?style=for-the-badge&labelColor=090909&color=e8e8ed&label=Coverage" alt="Coverage"></a>
+<a href="https://eneru.readthedocs.io/"><img src="https://img.shields.io/badge/Docs-Read%20The%20Docs-e8e8ed?style=for-the-badge&labelColor=090909" alt="Documentation"></a>
+<a href="https://pypi.org/project/eneru/"><img src="https://img.shields.io/pypi/v/eneru?style=for-the-badge&labelColor=090909&color=e8e8ed&label=PyPI" alt="PyPI"></a>
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/m4r1k/Eneru/main/docs/images/eneru-diagram.svg" alt="Eneru Architecture" width="600">

docs/changelog.md

@@ -9,14 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-> Status: v5.1.0-rc8 is the final candidate before v5.1.0 GA. The rc8
-> changes (`tui` CLI alias, TUI right-edge fix, graph axes/units,
-> events-list decoupling, time-windowed graph X positioning, parallel
-> E2E matrix, shell completion) are the last polish items from
-> hardware testing on rc7. Once GA the entry below is promoted from
+> Status: v5.1.0-rc9 is the final candidate before v5.1.0 GA. rc9
+> reframes the voltage-monitoring path for grid-quality reporting
+> (clamp warnings to ±10% nominal, add severity-aware notification
+> bypass) on top of rc8's TUI/E2E/completion polish. After Federico's
+> live-mains testing on rc9 the entry below is promoted from
 > `[Unreleased]` to `[5.1.0] - YYYY-MM-DD` with no other changes.
 
 ### Added
+- **rc9 — Grid-quality voltage reporting.** Voltage warning thresholds (`BROWNOUT_DETECTED` / `OVER_VOLTAGE_DETECTED`) are now derived as the **tighter** of the EN 50160 / IEC 60038 ±10% envelope and `input.transfer.{low,high}` ± 5V — never wider than ±10%. Wide UPS firmware defaults (typical APC: 170 / 280 on 230V) used to make warnings fire only ~5V before the UPS itself switched to battery; the clamp ensures warnings serve the operator's grid-quality question instead. Managed UPSes with narrow transfer points (e.g. 215 / 245) keep their existing tighter thresholds via the same clamp. New `MonitorState.ups_transfer_low/high` fields track the UPS firmware switch points separately for use in notification context. The startup log line is reformatted to show both grid-quality warnings and UPS battery-switch points on separate lines.
+- **rc9 — Severity-aware notification bypass.** Voltage deviations greater than ±15% from nominal now bypass `voltage_hysteresis_seconds` (default 30s) and notify **immediately**, with a `(severe, X.X% below/above nominal)` tag and an `Approaching UPS battery-switch threshold` callout when the UPS is likely to react soon. Mild deviations (10–15%) still go through the dwell so neighbour-appliance flap doesn't spam. The threshold (15%) is hard-coded — same reasoning as warning thresholds, no config knob to misconfigure.
+- **rc9 — Notification text overhaul.** `BROWNOUT_DETECTED` / `OVER_VOLTAGE_DETECTED` notifications now carry `% deviation`, the warning threshold, and (when NUT exposes them) the UPS firmware's switch points so the operator can distinguish "grid is wobbly" from "UPS is about to switch". Mild events read e.g. `input voltage 200.0V is 13.0% below 230V nominal (warning threshold 207.0V). Persisted 30s. UPS will not switch to battery until 170.0V (firmware setting); this is a grid-quality issue, not an imminent power loss.`
 - **rc8 — `eneru tui` CLI alias.** First-class subcommand, identical options + dispatch to `eneru monitor`. Both spellings show in top-level help; the same `--config / --once / --interval / --graph / --time / --events-only` options work for either.
 - **rc8 — Graph Y-axis labels, units, and now/min/max header in the live TUI.** Each graph panel prints a stat row under the title (`now: 100%   min: 95%   max: 100%`) and labels the top/middle/bottom rows of the chart with values + units (`100% ┤`, `50% ┤`, `0% ┤`). Voltage and runtime graphs use observed bounds (e.g. `235.4V` / `233.1V`); runtime values render as `45m 12s` instead of raw seconds.
 - **rc8 — Time-windowed X positioning in `BrailleGraph.plot`.** New optional `x_values` / `x_min` / `x_max` arguments place each sample at its actual time within the requested window instead of spreading evenly across the chart. Without this, a 12h dataset in a 30d view looked like 30 days of data; sparse data now stays in the leftmost slice and a `data: 12h of 30d requested` footer surfaces the gap. `--once` mode keeps the legacy behaviour by not passing the new arguments.
@@ -60,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **rc7 — Stats schema bumped 2 → 3.** Added `events.notification_sent INTEGER DEFAULT 1`. Auto-migrates v2 DBs via idempotent `ALTER TABLE` on first start; existing rows default to `1` (the v2 daemon always notified). Pattern documented as the second exercise of the schema-evolution mechanic introduced in rc6.
 
 ### Changed
+- **rc9 — Voltage warning thresholds may produce more notifications on wide-transfer UPSes.** Operators with default-wide UPS firmware (e.g. APC Smart-UPS 170/280 on 230V) previously got essentially zero `BROWNOUT_DETECTED` / `OVER_VOLTAGE_DETECTED` notifications because the warnings fired only just before the UPS itself reacted. After rc9, the same setup will fire warnings at the EN 50160 ±10% band (207 / 253 on 230V) — that is the goal. If your mains is consistently outside that envelope, you'll learn about it. If you don't want per-event pings for sub-30s flap, the existing `notifications.voltage_hysteresis_seconds` (default 30s) still filters mild events; severe events (>±15%) bypass it and notify immediately.
 - **rc8 — TUI events panel is decoupled from the graph timescale.** Pressing `<T>` to cycle the graph window (1h → 6h → 24h → 7d → 30d) no longer re-queries the events list. The events panel uses a fixed `EVENTS_TIME_WINDOW = 24 * 3600` regardless of `<T>`, and `<M>` keeps toggling between 8 and 50 max rows. The two controls are now orthogonal — the graph is the variable view, the events list is the stable recent-history view.
 - **rc8 — E2E workflow runs as a 4-way parallel matrix.** The single `e2e-test` job is replaced by four matrix jobs visible in the GitHub Checks tab as `E2E CLI`, `E2E UPS Single`, `E2E UPS Multi`, and `E2E Redundancy and Stats`. Setup steps are a composite action at `.github/actions/e2e-setup/`; test bodies live in `tests/e2e/groups/{group}.sh`. Total wall-clock is bounded by the slowest group instead of the sum of all 32 tests. **Operator action (one-time, manual):** branch protection on `main` previously required `e2e-test`. Replace it with the four new checks listed above. GitHub allows adding checks before they exist (status: *expected*), so do this immediately before/after the merge so PRs aren't blocked on a check that no longer runs.
 - **`shutdown_order` and `parallel` are now mutually exclusive.** Setting both on the same server is a hard validation error (previously a warning). Pick one model: `shutdown_order` for multi-phase ordering, or `parallel` for the legacy two-group behaviour.

docs/notifications.md

@@ -290,7 +290,27 @@ sqlite3 /var/lib/eneru/<UPS>.db \
 ```
 
 If the condition persists past the dwell, the notification fires
-with a `(persisted Ns)` annotation so you can see it was held.
+with a `Persisted Ns.` annotation so you can see it was held.
+
+**Severity bypass (rc9, 5.1.0).** Non-severe voltage warnings (up
+to and including ±15% from nominal) go through the dwell as
+described above. **Severe deviations** (greater than ±15% from
+nominal) bypass the dwell entirely and notify immediately, with a
+`(severe, X.X% below/above nominal)` tag and an
+`Approaching UPS battery-switch threshold` callout when NUT
+exposes the UPS's transfer points. The reasoning:
+- Non-severe events are usually flap from neighbour appliances
+  cycling — the 30s filter is the right call. Note that with
+  narrow UPS transfer points the warning thresholds may be tighter
+  than ±10%, so the "non-severe" band can fire at less than 10%
+  deviation; the dwell still applies.
+- Severe deviations indicate real grid trouble (utility fault,
+  generator instability, site wiring issue) — the operator wants
+  to know immediately, not 30s later.
+
+The bypass threshold (15%) is hard-coded — there's deliberately no
+config knob for it, same reasoning as the warning thresholds: a
+misconfiguration there would mask real over-voltage events.
 
 ### `notifications.suppress` — mute specific event types
 

docs/triggers.md

@@ -37,11 +37,33 @@ What Eneru does instead:
 1. **Auto-detect at startup.** Read `input.voltage.nominal` from NUT
    and snap it to the nearest standard grid voltage from
    `(100, 110, 115, 120, 127, 200, 208, 220, 230, 240)` if within 15V
-   tolerance. `warning_low` / `warning_high` derive as ±10% of the
-   snapped nominal (or from `input.transfer.{low,high}` when NUT
-   exposes those *and* they sit within sanity bounds of the snapped
-   nominal).
-2. **Cross-check with observed reality.** Some UPS firmwares (notably
+   tolerance.
+2. **Derive grid-quality warning thresholds.** `warning_low` /
+   `warning_high` are computed as the **tighter** of:
+   - the EN 50160 / IEC 60038 ±10% envelope (`nominal × 0.9` /
+     `nominal × 1.1`), and
+   - NUT's `input.transfer.{low,high}` ± 5V buffer (when NUT exposes
+     those *and* they sit within sanity bounds of the snapped nominal).
+
+   Tighter = warns earlier = better grid-quality signal. UPS firmware
+   defaults are often *wide* (typical APC: `transfer.low=170` /
+   `transfer.high=280` on 230V) to avoid switching to battery for
+   routine grid wiggles; if Eneru honored those without clamping, a
+   real-world brownout where mains drops to 200V (a 13% sag, definitely
+   operator-relevant) would never log `BROWNOUT_DETECTED`. The clamp
+   ensures Eneru's warnings serve the operator's grid-quality question
+   while the UPS firmware's switch points remain available separately
+   for context.
+
+   Behaviour table for a 230V nominal:
+
+   | UPS transfer points | warning_low / warning_high | Why |
+   |---------------------|----------------------------|-----|
+   | 170 / 280 (wide, APC default) | 207 / 253 | ±10% wins (transfer too wide) |
+   | 215 / 245 (narrow, managed) | 220 / 240 | transfer ± 5V wins (tighter) |
+   | not reported | 207 / 253 | ±10% fallback |
+
+3. **Cross-check with observed reality.** Some UPS firmwares (notably
    on US 120V grids) mis-report `input.voltage.nominal=230`. After
    ~10 polls Eneru takes the median of observed `input.voltage`
    readings and re-snaps the nominal if the readings disagree with
@@ -53,16 +75,30 @@ What Eneru does instead:
 
    If you see one of these rows, your UPS firmware is mis-reporting
    nominal — the daemon corrected for you, but it's worth filing a
-   NUT driver bug upstream.
-3. **Hysteresis on notifications, not on logs.** The state log line
-   for `OVER_VOLTAGE_DETECTED` / `BROWNOUT_DETECTED` is always
-   written immediately on transition. The *notification* dispatch is
-   debounced by `notifications.voltage_hysteresis_seconds` (default
-   30s). A 2-second flap to 122V on a 120V grid no longer pages you;
-   a sustained 30s over-voltage still does — and arrives with a
-   `(persisted Ns)` annotation. See
-   [Notifications → Tuning alert noise](notifications.md#tuning-alert-noise).
-4. **Per-event mute, with a safety blocklist.**
+   NUT driver bug upstream. The re-snap also re-applies the
+   tighter-of-±10%-and-transfer clamp against the new nominal.
+
+4. **Severity-aware notification hysteresis.** The state log line for
+   `OVER_VOLTAGE_DETECTED` / `BROWNOUT_DETECTED` is always written
+   immediately on transition. The *notification* dispatch is gated by
+   severity:
+   - **Non-severe voltage warnings** (up to and including ±15% from
+     nominal) go through `notifications.voltage_hysteresis_seconds`
+     (default 30s). A 2-second flap to 105V on a 120V grid (12.5%
+     under nominal — past the warning threshold but not severe) no
+     longer pages you; a sustained event still does, and arrives
+     with a `Persisted Ns.` annotation. With narrow UPS transfer
+     points the warning band can be tighter than ±10%, so non-severe
+     events can fire at less than 10% deviation.
+   - **Severe deviations** (`>±15%` from nominal) bypass the dwell
+     and notify **immediately** with a `(severe, X.X% below/above
+     nominal)` tag. These signal real grid trouble — utility fault,
+     generator instability, site wiring — that the operator wants to
+     know about NOW, not 30 seconds from now.
+
+   See [Notifications → Tuning alert noise](notifications.md#tuning-alert-noise).
+
+5. **Per-event mute, with a safety blocklist.**
    `notifications.suppress: [...]` mutes specific informational
    events (AVR cycling, voltage normalized) but rejects safety-
    critical event names at config-load time. There is no way to
@@ -72,16 +108,40 @@ What Eneru does instead:
 
 ### What you'll see in the log
 
-```
-📊 Voltage Monitoring Active. Nominal: 230V (NUT=230). Low Warning: 207.0V. High Warning: 253.0V.
+```text
+📊 Voltage Monitoring Active.
+   Nominal: 230.0V (NUT=230.0).
+   Grid-quality warnings: 207.0V / 253.0V (±10% nominal, EN 50160 envelope).
+   UPS battery-switch points: 170.0V / 280.0V (from NUT input.transfer.{low,high}).
 📊 Voltage auto-detect re-snap: NUT=230V disagreed with observed median 120.0V (window=[120.5, 119.0, ...]V). Re-snapped to 120V; new thresholds 108.0V / 132.0V.
 ⚡ POWER EVENT: VOLTAGE_AUTODETECT_MISMATCH - NUT nominal=230V, observed median=120.0V, re-snapped to 120V
 ```
 
-The bottom row also lands in the SQLite `events` table with
+The autodetect-mismatch row lands in the SQLite `events` table with
 `notification_sent=0` so it doesn't ping you (it's startup
 information, not an active power event).
 
+### What you'll see in a brownout notification
+
+**Mild brownout (UPS won't switch):**
+
+```text
+🔻 BROWNOUT_DETECTED: input voltage 200.0V is 13.0% below 230V nominal
+   (warning threshold 207.0V). Persisted 30s.
+   UPS will not switch to battery until 170.0V (firmware setting);
+   this is a grid-quality issue (outside the EN 50160 ±10% envelope),
+   not an imminent power loss.
+```
+
+**Severe brownout (UPS may switch shortly):**
+
+```text
+🔻 BROWNOUT_DETECTED: (severe, 21.7% below nominal): input voltage 180.0V.
+   Notifying immediately (bypassed hysteresis).
+   Approaching UPS battery-switch threshold (170.0V) -- battery may
+   engage shortly.
+```
+
 ---
 
 ## Low battery threshold