---
name: plenum-architecture-contract
description: >-
  The load-bearing design decisions of Plenum (smart-thermostat-with-vents),
  the invariants that must hold, WHY each exists, and the known-weak points.
  Load when you need the canonical temperature-unit contract (°F storage,
  single write boundary, #231), the component map with real file paths, the
  cycle-engine invariants (mode lock, in-place trigger updates, 60s tick), the
  MCP loopback design, or a "before you change X, understand Y" dependency
  check. Also load when CLAUDE.md prose seems to disagree with the repo — this
  skill flags the known drift.
---

# Plenum architecture contract

The design decisions this system stands on, stated as invariants with their
rationale. Every claim below was verified against the repo at v0.22.1
(2026-07-04). Where `DESIGN.md` prose has drifted behind the code (or
`CLAUDE.md` had, before the 2026-07-05 corrections in PR #388), the drift is
called out — **the repo files win**.

**When NOT to use this skill:**
- Domain theory (why short-cycling kills compressors, what a deadband is, HA
  entity semantics) → `hvac-zoning-reference`.
- The blow-by-blow story of a past incident → `plenum-failure-archaeology`.
- Which CI gates a change must clear, PR/release mechanics → `plenum-change-control`.
- Diagnosing a live symptom → `plenum-debugging-playbook`.
- Adding/locating a config knob → `plenum-config-and-flags`.

Jargon (once): *write boundary* — the POST/PUT/PATCH handlers in
`smart_vent/backend/api/routes.py`, the only place display-unit input becomes
storage °F. *Delta* — a temperature difference (deadband, offset): °C↔°F scales
by 9/5 with **no** 32 offset. *Ingress* — Home Assistant's authenticated
reverse proxy that serves the add-on UI. *Zone* — one thermostat plus its rooms.

---

## 1. Component map (verified file paths and responsibilities)

All backend paths are under `smart_vent/backend/`.

```
HA Core ◄─ WebSocket + REST ─► ha_client.py ◄── engine/ ◄── scheduler.py ◄── api/routes.py ◄── frontend / MCP
                                                    │              │                │
                                                    └──────────────┴── db.py ── app.db (SQLite, DATA_DIR)
```

| File | Responsibility (verified) |
|---|---|
| `main.py` | Entry point. Binds aiohttp on `PORT` (default **8099**), starts the HA client task, the `Scheduler`, and the HTTP MCP server (uvicorn) on `MCP_PORT` (default **9099**). One-shot `flair.db → app.db` rename (#89). Security-headers middleware on every response. |
| `ha_client.py` | Raw HA WebSocket client + state cache. Normalises **sensor** readings to °F via per-entity `unit_of_measurement` (`get_numeric_state`, line ~172), resolves HA's system unit into `ha_temp_unit` from `/api/config` (#281), and converts stored-°F setpoints back to HA-native units on write via `_setpoint_to_native` (#280). Dev mode intercepts all writes here and logs `[DEV] Would …` instead. |
| `scheduler.py` | Orchestrator. Owns `_engines: dict[thermostat_id → CycleEngine]`, the 60s APScheduler `main_tick`, log purge (24h), schedule-expiry sweep (60s, #359), daily/monthly metrics rollups (#85). Owns `_active_unit` and the `system_enabled` / `developer_mode` flags (persisted in `system_settings`). |
| `engine/cycle_engine.py` | One instance **per thermostat**. The `IDLE → RUNNING → TERMINATING → IDLE` state machine; all safety guards (short-cycle lockout, cooling lockout, staleness filter, cycle timeout, airflow floor, #367 envelope enforcement) live in its tick. ~3600 lines. |
| `engine/room_manager.py` | Resolves each room's active trigger: override > schedule > presence holdover. |
| `engine/vent_controller.py` | Issues cover open/close commands per the room-vent `control_method`. |
| `api/routes.py` | All REST endpoints. **The write boundary**: every temperature field is converted via the `units.py` helpers here, then bounds-checked on the °F value. Also `TEMPERATURE_FIELDS` (Python side of the parity system). |
| `api/ws_handler.py` | Thin WebSocket broadcaster (`WSManager`). Event payloads are built in `scheduler.py` / the engine — temperatures in them are raw °F. |
| `units.py` | The four converters: `to_f` / `delta_to_f` / `from_f` / `from_f_delta`. Single source of truth shared by routes.py, ha_client.py, and the engine's HA-ingest helper. |
| `db.py` | aiosqlite layer. `SCHEMA` script (WAL mode, FK on) + append-only `_MIGRATIONS` list of `ALTER TABLE` statements + two one-shot data migrations gated by `system_settings` sentinels. |
| `tz.py` | Single source of local-time truth: `TZ` env (from the `timezone` add-on option via `run.sh`). Schedule matching and metrics bucketing use it; **storage timestamps are UTC**. |
| `mcp_http.py` / `mcp_openapi.py` | HTTP (Streamable) MCP server on port 9099; tools generated from the OpenAPI spec, each call dispatched over **loopback HTTP** to the REST API. |
| `frontend/src/contexts.ts` | `buildUnitContext(unit)` — the frontend display-conversion layer (`toDisplay`, `toDisplayDelta`, `fmtTemp`). |

`DESIGN.md` is the **original** design doc and is stale in places (it still
describes a stdio/SSE MCP server, `min_open_vents` as a count, a 30s monitor
tick). Treat it as historical intent; this skill and the code are current.

---

## 2. The temperature-unit contract (canonical statement — owned here)

**Invariant: every temperature at rest or in flight inside the system is °F.**
SQLite rows, engine arithmetic, scheduler state, WebSocket event payloads, API
GET responses — all °F, always (Issue #123). Exactly **three** places convert,
and nothing else may:

1. **Backend write boundary** (`api/routes.py`): display-unit input → °F via
   `to_f` / `delta_to_f` (imported from `units.py` as `_to_f` / `_delta_to_f`),
   using the active unit from `scheduler.get_temperature_unit()`. Bounds
   (40–90 °F for targets, 40–100 °F for setpoints, 0–10 °F for
   deadband_override) are checked **after** conversion, on the °F value —
   checking the raw input is meaningless when the unit varies
   (`.jules/sentinel.md`, 2026-05-05).
2. **Frontend display layer** (`contexts.ts`): °F → display via `toDisplay` /
   `toDisplayDelta` / `fmtTemp`, for rendering and form **initialisation
   only**. Forms hold display-unit values and submit them raw.
3. **HA I/O boundary** (`ha_client.py` + `_climate_temp_to_f` in
   `cycle_engine.py`): HA-native values ↔ °F. Sensor entities carry a
   per-entity `unit_of_measurement`; `°C` readings are normalised through the
   shared `to_f` (#251). Climate entities report in HA's *system* unit
   (`ha_temp_unit`, resolved from `/api/config` — #281 fixed the detection),
   so climate reads pass through `_climate_temp_to_f` and setpoint writes
   through `_setpoint_to_native` (#280 — sending raw °F to a metric HA would
   be interpreted as °C and drive the HVAC wildly wrong).

**The frontend NEVER calls `toStorage` / `toStorageDelta` on an outgoing
payload.** That was **#231**: the Thermostats form converted 16 °C → 60.8 °F
via `toStorage`, then the backend's `_to_f` converted again → 141.44 °F
stored. Each side's unit tests passed because each asserted a different
contract. The conversion belongs to exactly one side — the backend. The
`toStorage` helpers still exist in `contexts.ts` but are reserved for local
validation-bound math only.

**Absolute vs delta is a type distinction, not a detail.** Absolute uses
`(f−32)×5/9`; a delta uses only `×5/9`. Feeding a delta (deadband, temp_offset,
overshoot_delta) through the absolute converter renders a 2 °F deadband as a
negative °C number (#291 was exactly this in a chart subtitle). `units.py`
keeps all four converters side by side to make the axis visible.

**The parity system** keeps the contract enforced: every write-boundary
temperature field is registered in `TEMPERATURE_FIELDS` in both `routes.py`
(12 fields as of v0.22.1) and `e2e/tests/temperature-fields.ts`, with
`// @covers:` round-trip tests, and
`backend/tests/test_temperature_field_parity.py` fails CI on any drift. The
add-a-field procedure and gates are owned by `plenum-change-control`; the
parity-rule details by `plenum-validation-and-qa`.

**History note:** older CLAUDE.md copies placed `_to_f`/`_delta_to_f`/`_from_f`
in `backend/api/routes.py`; CLAUDE.md was corrected 2026-07-05 (PR #388). They
live in `backend/units.py` and are imported into routes.py under those aliases
(routes.py lines 35–38). Same semantics; trust `units.py`.

---

## 3. Engine and scheduler invariants

| Invariant | Why | Where verified |
|---|---|---|
| **One `CycleEngine` per thermostat; 60s tick.** The scheduler's `_sync_engines` creates/removes engines as thermostats appear in room configs; `main_tick` runs every 60s (`max_instances=1, coalesce=True`) and also fires on HA state changes. Each engine serialises its work behind an internal `asyncio.Lock`. | Zones are independent failure domains; one thermostat's outage must not stall another's control loop (#286 hardened the per-engine exception isolation). | `scheduler.py` lines ~53, 130–137, 470–481; `cycle_engine.py` `tick()` line 176. |
| **Mode is locked at cycle start** (`_cycle_mode`, cycle_engine line 100). Monitoring, at-target checks, and the setpoint all use the locked mode, not live `hvac_action`. | During HVAC idle phases the naively inferred mode can flip tick-to-tick → heat/cool oscillation. A room that now needs the *opposite* direction is dropped by the mode filter; if no compatible rooms remain the cycle ends cleanly and a new one may start opposite on the next tick. | `docs/cycle-engine.md` §"Why the mode is locked"; `cycle_engine.py` lines ~404, 546, 566. |
| **Mid-cycle trigger changes are applied in place, never by teardown** (#215). A changed source/target updates the running cycle and re-derives the setpoint; the cycle log stays open with a `trigger updated in place` setpoint-history entry. | The old teardown was itself a compressor stop/start — and with the #208/#214 off-time lockout enabled, the rebuild was then *blocked* for the lockout window, leaving a room unconditioned (back-to-back schedule blocks at 08:00 caused a full furnace stop→start for a target that only moved up). | `cycle_engine.py` lines ~886–911, 972; `docs/safety.md` §"In-place cycle updates". |
| **The engine never converts display units.** It receives °F from the DB and commands °F; `ha_client.py` translates to HA-native at the wire. The only conversion helpers it touches are the HA-ingest normalisers (`_climate_temp_to_f`, `to_f` on °C sensors). | Conversion in two layers is how #231 happened; the engine staying unit-blind keeps the write boundary the single converter. | `cycle_engine.py` `_climate_temp_to_f` docstring (line 3589). |
| **The scheduler owns `_active_unit`.** Resolution order: `TEMPERATURE_UNIT` env override → HA `/api/config` on startup → last-known `system_settings.temperature_unit`. Engine and routes read it via `scheduler.get_temperature_unit()`, never from the DB directly. | One synchronous, cached source; a mid-request DB read could race a unit change. Unit changes set `unit_change_ack_required` and surface a banner rather than silently re-labelling data. | `scheduler.py` lines ~61, 102–105, 293–295, 366–374. |
| **`EntityState.numeric` is always °F.** `POST /api/ha/states` converts `°C` entity values to °F (and rewrites the unit label) before returning. | The frontend must apply exactly one conversion (`fmtTemp`); if raw HA values leaked through, °C sensors would double-convert on display. | `routes.py` lines ~1378–1387. |
| **MCP dispatches via loopback HTTP — one write boundary** (#372, shipped 0.22.0/0.22.1). Tools are generated from the OpenAPI spec; every call becomes `session.request(...)` against `http://127.0.0.1:8099`, hitting the same handlers, validation, unit conversion, and logging as the UI. The MCP server is a separate ASGI (Starlette/uvicorn) stack on port 9099 because aiohttp is not ASGI; `/mcp` returns 503 unless the `mcp_enabled` toggle is on (off by default). | "No duplicated business logic, no #231 double-conversion" — the module docstring says it outright. A second code path into the DB would eventually drift from the write boundary. | `mcp_http.py` (whole file, esp. docstring and `dispatch_tool`); `main.py` `_start_mcp_server`; `docs/mcp.md`. |
| **System-off means no HA writes.** With `system_enabled` false (and dev mode off), the engine tick returns before any control logic; the sole exception is a one-time abort of a cycle that was in flight when the system was disabled (which restores setpoint/vents). Idle-state vent reconciliation is also gated on enabled. Dev mode goes further: `ha_client` intercepts every write and logs `[DEV] Would …`. | An operator disabling the system must be able to trust that Plenum stops touching their equipment, without leaving a half-run cycle holding the thermostat at an overshot setpoint. | `cycle_engine.py` lines 315–322, 376; `ha_client.py` dev_mode branches (lines ~287, 317, 335). |
| **SQLite, single file `app.db` in `DATA_DIR`, WAL mode; `system_settings` is a key-value table** (flags: `temperature_unit`, `unit_change_ack_required`, `system_enabled`, `developer_mode`, `mcp_enabled`, `sensor_stale_after_min`, migration sentinels, …). No settings table, no ORM. | Zero-dependency persistence fitting the add-on model; KV avoids a schema migration per flag. `DATA_DIR` is `/config` in the add-on (config.yaml `environment:`), `/data` by default elsewhere. | `db.py` SCHEMA (line 38, `system_settings` at 189); `main.py` lines 42–43. |
| **WebSocket events carry raw °F.** Zone-status payloads are built from engine state (already °F); the frontend converts for display. | Same single-conversion rule as REST GETs. | `scheduler.py` `_zone_status_dict`; `api/ws_handler.py` is payload-agnostic. |
| **All schedule times are local wall-clock in the configured timezone; storage timestamps are UTC.** `tz.py` is the only legitimate source of "local now" — it reads `TZ` (from the `timezone` add-on option via `run.sh`). Schedule `start_time`/`end_time`/`expires_at` are naive local; cycle/event timestamps are `datetime.now(UTC)`. | Mixing the two produced real bugs: #65 (holdovers stored local, compared as UTC), #294 (vacation modal min computed in UTC), #301 (naive-UTC rendered as local). | `tz.py` module docstring; `db.py` schedules table comment (line 89) and `_migrate_holdover_timestamps_to_utc`. |
| **Safety monitoring must survive degraded states.** The thermostat-availability check runs *before* the enabled/vacation guards; a sustained outage with a cycle in flight aborts it after `unavailable_abort_after_min` (default 5). The #367 envelope check runs even with zero active rooms. | #267: an unavailable thermostat used to suspend *all* per-tick safety monitors while the physical HVAC kept running at the last commanded setpoint with vents closed. #367: with no active rooms, nothing enforced `max_setpoint`. | `cycle_engine.py` lines 263–300 (with the #267 comment), 358–381. |

---

## 4. Known-weak points (stated plainly)

| Weakness | Status | Detail |
|---|---|---|
| **No authentication on the direct ports** | **Open — #373**, the biggest open design problem | Ingress access is authenticated by HA, but `config.yaml` lets users publish 8099 (web UI) and 9099 (MCP) directly, and neither has any auth. The MCP endpoint exposes the **full write surface**; its only guards are "off by default" and "port unpublished by default". Do not add features that assume a trusted network without checking #373's direction first. |
| **Ad-hoc DB migrations** | **Open — #21** | `_MIGRATIONS` is a list of `ALTER TABLE` strings run under `try/except: pass` ("column already exists") on every startup — no version table, no ordering guarantees, no down-migrations, and a genuinely failing migration is silently swallowed. Two one-shot data migrations use `system_settings` sentinels instead. Unwritten-but-observed rule (inferred from history): schema changes are additive-only, never lossy. |
| **Container runs as root** | **Open — #23** (docker hardening; see also #173 base image) | No `USER` directive; the add-on process has root in-container. |
| **Heat pumps unsupported** | Deliberate scope cut | Stated in `docs/safety.md`. The cooling lockout has no heating equivalent because a conventional furnace is assumed; reversing-valve/defrost semantics would invalidate several guards. Don't "fix" cold-weather heating behaviour by analogy with the cooling lockout. |
| **OpenAPI decorators are documentation-only** | Verified current at v0.22.1 | `@docs` / `@request_schema` / `@response_schema` (`api/openapi.py`, #188) install **no validation middleware** — handlers parse `await request.json()` themselves. #295 (closed) did **not** add schema-driven validation; it added targeted per-field validators in routes.py: `_THERMO_NUMERIC_BOUNDS` + `_validate_thermostat_numeric` for the safety-critical numeric fields, `_validate_deadband_override`, `_validate_ambient_suppression`. Any *new* body field is unvalidated unless you validate it by hand — the schema will happily document a constraint nobody enforces. |
| **`DESIGN.md` is stale** | Historical doc | See §1. `docs/` pages are the docs of record for shipped behaviour. |
| **CLAUDE.md drift** | Trust the repo files; CLAUDE.md corrected 2026-07-05 (PR #388) | The 2026-07-04 audit found and fixed: (a) unit helpers live in `backend/units.py`, not routes.py (§2); (b) the visual-regression E2E suite lives in `.github/workflows/container-ci.yml` — there is **no** `e2e.yml` anymore; (c) coverage thresholds ratcheted (backend `fail_under` 93.9 as of 2026-07; table of record: `plenum-validation-and-qa` §6). If CLAUDE.md and the repo disagree again, the repo wins — re-run the Provenance checks. |

---

## 5. Before you change X, understand Y

| Before you change… | …understand | Because |
|---|---|---|
| Any temperature field on a write path | §2 in full + the 3-file parity system (`plenum-change-control` §2.1) | The exact #231 bug class; parity CI fails on any one-sided edit. |
| Conversion math anywhere | Absolute-vs-delta axis (`units.py` docstring; `hvac-zoning-reference` §4) | The wrong axis silently corrupts values (#291). |
| `_do_tick` guard ordering in `cycle_engine.py` | Availability check < enabled < vacation < heat_cool revert < active rooms < safety rooms (#367) — the order **is** the safety model | #267 happened because everything lived below a guard that returned early. Moving a guard can silently suspend the monitors beneath it. |
| Cycle teardown / `_abort_cycle` call sites | In-place update rule (#215) + off-time lockout interaction (#208/#214) | Every new teardown path is a potential short-cycle, and the lockout then blocks the restart. |
| Mode inference or the mode filter | Mode-lock invariant (§3) and opposite-cycle prevention (`docs/safety.md`) | Oscillation is the failure mode the lock exists to prevent. |
| Minimum-runtime hold / overflow logic | `docs/overflow-conditioning.md` tiering + the `in_min_runtime_hold` close-loop gate | #237: without the gate, the close loop re-closes vents the hold just opened (churn); tier-3 headroom exclusion is what makes "cannot create an opposite cycle by construction" true. |
| `ha_client.py` read/write paths | The HA I/O boundary (§2 item 3) | #280/#281: climate entities use HA's *system* unit, sensors use per-entity units — they need different normalisation. |
| Anything reading "now" for schedules/metrics | `tz.py` contract (local wall-clock via `TZ`; storage in UTC) | #65/#294/#301 were all naive-time mixups. |
| `Scheduler` job wiring or engine lifecycle | One-engine-per-thermostat + `_tick_engine` exception isolation (#286) | A pre-tick exception used to silently stop a zone being controlled. |
| REST handlers / adding endpoints | Decorators don't validate (§4); CWE-209 rule (`log.exception` + generic `error(...)`); every knob needs a UI control | All three are standing rules; the MCP surface auto-inherits every endpoint you add, unauthenticated (#373). |
| DB schema | Additive-only `_MIGRATIONS` pattern + sentinel data-migrations (§4, #21) | There is no rollback; a lossy migration bricks user data on upgrade. |
| MCP tool behaviour | Loopback design (§3) — fix the REST handler, not the tool | Tools are generated; there is nothing MCP-side to patch without recreating the dual-path problem. |
| Anything rendered in the UI | Golden screenshots + `<Frozen>` determinism (owned by `plenum-ci-and-release` / CLAUDE.md) | Visual-regression legs in container-ci fail until goldens regenerate in both unit sets. |

---

## Provenance and maintenance

All facts verified 2026-07-04 against v0.22.1 (`smart_vent/config.yaml`).
Volatile facts and how to re-verify:

- **Helper location / aliases**: `grep -n "from ..units import" smart_vent/backend/api/routes.py` (lines 35–38 as of 2026-07).
- **TEMPERATURE_FIELDS count (12, recounted 2026-07-05)**: `grep -c '":' <(sed -n '/^TEMPERATURE_FIELDS/,/^}/p' smart_vent/backend/api/routes.py)` → 12, or read routes.py lines ~243–262.
- **Ports 8099/9099**: `grep -n "PORT" smart_vent/backend/main.py`; `grep -n "tcp" smart_vent/config.yaml`.
- **Tick cadence / jobs**: `grep -n "add_job" -A4 smart_vent/backend/scheduler.py`.
- **Coverage thresholds** (ratchet upward over time): `grep fail_under smart_vent/pyproject.toml`; `grep -A4 "lines:" smart_vent/frontend/vite.config.ts`.
- **Workflows** (e2e.yml is gone): `ls .github/workflows/`.
- **#295 validation state** (re-check if a validation middleware ever lands): `grep -n "_THERMO_NUMERIC_BOUNDS\|request_schema" smart_vent/backend/api/routes.py smart_vent/backend/api/openapi.py`.
- **Open weak-point issues**: #373 (auth), #21 (migrations), #23 (docker hardening) — confirm still open via `gh issue view <n>` before citing as open.
- **`system_settings` keys in live use**: `grep -rn "get_system_setting(" smart_vent/backend --include=*.py -h | grep -o '"[a-z_]*"' | sort -u`.