# v0.7.0 — Home Assistant + Matter integration

**Branch**: `feat/adr-115-ha-mqtt-matter` (PR [#778](https://github.com/ruvnet/RuView/pull/778)) · **Tracking issue**: [#776](https://github.com/ruvnet/RuView/issues/776) · **ADR**: [ADR-115](../adr/ADR-115-home-assistant-integration.md)

## TL;DR

RuView ships first-class integration into Home Assistant via MQTT auto-discovery and scaffolding for cross-ecosystem Matter Bridge support. One `--mqtt` flag and HA auto-creates **21 entities per node**: 11 raw signals plus 10 inferred semantic primitives (someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting-in-progress, bathroom-occupied, fall-risk-elevated, bed-exit, no-movement, multi-room-transition). The semantic primitives are the architectural keystone — they run server-side, so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states*. That's the architectural win that makes RuView deployable in healthcare and AAL contexts.

Plus 3 starter HA Blueprints, 3 drop-in Lovelace dashboards, an ESP32 hardware-validation harness, a witness bundle that self-verifies, and **420 lib tests including ~2,560 fuzzed assertions** per CI run.

## What's new for end users

### Home Assistant integration (HA-DISCO)
- New `--mqtt` flag on `wifi-densepose-sensing-server` (gated behind `--features mqtt` Cargo flag)
- Auto-discovers as 21 entities per node — see [`docs/integrations/home-assistant.md`](../integrations/home-assistant.md) for the full table
- mTLS support, configurable per-entity publish rates, `--privacy-mode` for healthcare/AAL deployments
- Pinned tested against **Home Assistant Core 2025.5** + **Mosquitto 2.0.18**

### Matter Bridge scaffolding (HA-FABRIC)
- New `--matter` flag wires the bridge plumbing — cluster mapping, endpoint tree, commissioning code
- v0.7.0 ships **SDK-independent** — actual `rs-matter` integration deferred to v0.7.1 per ADR §9.10
- Bridge tree spec defines Apple Home / Google Home / Alexa / SmartThings exposure

### Semantic Automation Primitives (HA-MIND)
The inference layer that moves RuView from "RF sensor" to "ambient intelligence infrastructure". 10 v1 primitives, each with warmup gate + hysteresis + explainability tags. Per-primitive precision/recall published in [`docs/integrations/semantic-primitives-metrics.md`](../integrations/semantic-primitives-metrics.md).

### 8 Starter HA Blueprints
Ready-to-import YAML under [`examples/ha-blueprints/`](../../examples/ha-blueprints/) covering distress notification, sleep-aware hallway dimming, wake routines, elderly inactivity escalation, meeting room automation, bathroom fan, fall risk escalation, auto-arm security.

### 3 Lovelace Dashboards
Drop-in views under [`examples/lovelace/`](../../examples/lovelace/) — single-room overview, multi-node grid, healthcare/AAL care view (privacy-mode-compatible).

## What's new for operators

| Flag | Purpose |
|---|---|
| `--mqtt`, `--mqtt-host`, `--mqtt-port`, `--mqtt-username`, `--mqtt-password-env`, `--mqtt-client-id`, `--mqtt-prefix` | Broker connectivity |
| `--mqtt-tls`, `--mqtt-ca-file`, `--mqtt-client-cert`, `--mqtt-client-key` | TLS / mTLS |
| `--mqtt-refresh-secs`, `--mqtt-rate-{vitals,motion,count,rssi,pose}`, `--mqtt-publish-pose` | Rate control |
| `--privacy-mode` | Strip HR/BR/pose at the wire boundary |
| `--matter`, `--matter-setup-file`, `--matter-reset`, `--matter-vendor-id`, `--matter-product-id` | Matter bridge |
| `--semantic`, `--semantic-thresholds-file`, `--semantic-zones-file`, `--semantic-baseline-window-days`, `--no-semantic <PRIMITIVE>` | Inference layer |

Full CLI matrix: [`docs/integrations/home-assistant.md`](../integrations/home-assistant.md#configuration).

## What's new for developers

- **`mqtt` Cargo feature** on `wifi-densepose-sensing-server` (adds `rumqttc 0.24` with rustls)
- **`matter` Cargo feature** — scaffolding only, no SDK pulled in
- New modules: `mqtt::{config,discovery,privacy,publisher,security,state}` and `semantic::{bus,common,sleeping,distress,room_active,elderly_anomaly,meeting,bathroom,fall_risk,bed_exit,no_movement,multi_room}` and `matter::{clusters,bridge,commissioning}`
- **420 unit tests passing** including 10 `proptest` cases that fuzz the wire boundary + semantic dispatch (~2,560 fuzzed assertions per CI run)
- **3 integration tests** against real Mosquitto in `.github/workflows/mqtt-integration.yml`
- **6 criterion benchmarks** — see [`docs/integrations/benchmarks.md`](../integrations/benchmarks.md)
- **ESP32 validation harness** — `scripts/validate-esp32-mqtt.sh` runs end-to-end against attached hardware
- **Witness bundle generator** — `scripts/witness-adr-115.sh` produces self-verifying tarballs

## Benchmarks (laptop, release build)

| Hot path | Measured | Target | Better |
|---|---|---|---|
| `state::event_fall` encode | 259 ns | <2 µs | 7.7× |
| `rate_limiter::allow_first` | 49.7 ns | <100 ns | 2× |
| `rate_limiter::allow_within_gap` | 62.1 ns | <100 ns | 1.6× |
| `privacy::decide_hr_strip` | 0.24 ns | <50 ns | 208× |
| `privacy::decide_presence_keep` | 0.24 ns | <50 ns | 208× |
| `semantic::bus_tick_all_10_primitives` | 717 ns | <10 µs | 14× |

Every target beaten by ≥1.6×, several by 100×+. Full numbers + reproduction recipe in [`docs/integrations/benchmarks.md`](../integrations/benchmarks.md).

## Security

- **Wire-boundary audit** (`mqtt::security`) — topic-segment safety (rejects MQTT wildcards `+`/`#`, NUL, `/`), TLS path safety (NUL/newline rejection), 32 KB payload-size cap, credential-hygiene canary (`--mqtt-password` regression-detector), `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path
- **5 property-based fuzz cases** in `mqtt::security::tests` covering random Unicode + injected wildcards/NULs at arbitrary offsets
- **`--privacy-mode`** enforced at every layer — discovery suppression + state stripping + Matter cluster gating

## Reproducibility

```bash
git checkout v0.7.0
cd v2
cargo test -p wifi-densepose-sensing-server --no-default-features --lib       # 420 passed
cargo test -p wifi-densepose-sensing-server --features mqtt --no-default-features --lib   # also 420 passed
RUVIEW_RUN_INTEGRATION=1 cargo test -p wifi-densepose-sensing-server \
    --features mqtt --no-default-features --test mqtt_integration -- --test-threads=1
cargo bench -p wifi-densepose-sensing-server --features mqtt --bench mqtt_throughput
cd ..
bash scripts/witness-adr-115.sh
cd dist/witness-bundle-ADR115-*/ && bash VERIFY.sh   # "ADR-115 witness bundle: VERIFIED ✓"
```

## Deferred to v0.7.1

- **P8b** — actual `rs-matter` SDK wiring (BIND/READ/INVOKE against the locked cluster/bridge/commissioning contract)
- **P9b** — multi-controller validation pairing one bridge into Apple Home + Google Home + HA Matter simultaneously
- **CSA Matter certification decision gate** — dev VID `0xFFF1` is fine for personal/HA-only; commercial deployment needs the vendor ID

## Deferred to v0.8.0

- Hard-fail plaintext MQTT on non-localhost broker (currently WARNs; `RUVIEW_MQTT_STRICT_TLS=1` opt-in already lands)
- HACS-native Python integration as MQTT-broker-free alternative (per ADR §6.A)

## Acknowledgements

Maintainer ACK on all 13 ADR §9 open questions (#776). 17 commits on the feat branch, each phase-tagged. PR review: [#778](https://github.com/ruvnet/RuView/pull/778).
