plenum-architecture-contract

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)

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

Content truncated.