From f40b811bee39855ca0e9d58566dcf345679cb75f Mon Sep 17 00:00:00 2001 From: ruv Date: Sat, 23 May 2026 15:19:18 -0400 Subject: [PATCH] docs(adr-115): v0.7.0 release notes + CHANGELOG refresh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## `docs/releases/v0.7.0-mqtt-matter.md` (new) Full release-readiness document for the v0.7.0 cut. Sections: - TL;DR — the architectural win in one paragraph - What's new for end users (HA-DISCO + HA-FABRIC + HA-MIND + 8 blueprints + 3 Lovelace dashboards) - What's new for operators (full CLI matrix) - What's new for developers (feature flags, modules, test counts, integration tests, benchmarks, validation harness, witness) - Benchmark numbers (all ADR §3.7 targets beaten 1.6×–208×) - Security (wire-boundary audit + 5 fuzz cases + --privacy-mode architectural win) - Reproducibility recipe (one block to verify the whole stack) - Deferred-to-v0.7.1 (P8b rs-matter SDK wiring + P9b multi-controller validation + CSA cert decision) - Deferred-to-v0.8.0 (hard-fail plaintext + HACS-native integration) - Acknowledgements (#776, #778, 17 commits, maintainer ACK) ## CHANGELOG.md — refreshed Unreleased entry The Unreleased ADR-115 bullet was written at 372 tests. Updated to: - **420 lib tests** (proptest fuzzing added in 0f7a4bd36 + b41fdd75c) - ~2,560 fuzzed assertions per CI run - 8 starter blueprints + 3 Lovelace dashboards (originally promised 3 blueprints — over-delivered) - mosquitto-backed integration tests + criterion benchmarks - ESP32 validation harness + witness bundle - Links to release notes + tracking issue + PR - Codename trio: HA-DISCO + HA-FABRIC + HA-MIND (the third belonged in the changelog all along) Refs #776, PR #778. Co-Authored-By: claude-flow --- CHANGELOG.md | 2 +- docs/releases/v0.7.0-mqtt-matter.md | 104 ++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 docs/releases/v0.7.0-mqtt-matter.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9302614c..aca65ab5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 they can be reintroduced with a real implementation. ### Added -- **Home Assistant + Matter integration (ADR-115).** New `--mqtt` and `--matter` flags on `wifi-densepose-sensing-server` expose the full sensing capability set to any Home Assistant install via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings) via a built-in Matter Bridge (HA-FABRIC). Includes 21 entity kinds — 11 raw signals + 10 semantic primitives (someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room-transition). The semantic primitives run server-side so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states* — the architectural win for healthcare and AAL deployments. Three starter HA Blueprints (distress notify, hallway dim on sleeping, wake routine on bed exit), Lovelace dashboard examples, mTLS support, 32 KB payload-size cap, MQTT-wildcard topic-injection rejection. **372 tests** cover the implementation. See [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md), [`docs/integrations/semantic-primitives-metrics.md`](docs/integrations/semantic-primitives-metrics.md), [`docs/adr/ADR-115-home-assistant-integration.md`](docs/adr/ADR-115-home-assistant-integration.md), and tracking issue [#776](https://github.com/ruvnet/RuView/issues/776). Matter SDK spike (P7) and CSA-certification path (P10) deferred to v0.7.1+ per ADR §9.10. Try it: `cargo run -p wifi-densepose-sensing-server --features mqtt --example mqtt_publisher -- --mqtt --mqtt-host 127.0.0.1`. +- **Home Assistant + Matter integration (ADR-115).** New `--mqtt` and `--matter` flags on `wifi-densepose-sensing-server` expose the full sensing capability set to any Home Assistant install via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings) via a built-in Matter Bridge scaffolding (HA-FABRIC, SDK wiring v0.7.1). Includes 21 entity kinds per node — 11 raw signals + 10 inferred semantic primitives (HA-MIND: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room-transition). The semantic primitives run server-side so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states* — the architectural win for healthcare and AAL deployments. Ships **8 starter HA Blueprints** under `examples/ha-blueprints/`, **3 drop-in Lovelace dashboards** under `examples/lovelace/` (including a privacy-mode-compatible healthcare care view), mTLS support, 32 KB payload-size cap, MQTT-wildcard topic-injection rejection, `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path. **420 lib tests** cover the implementation including **~2,560 fuzzed assertions per CI run** (10 proptest cases across wire-boundary security + semantic-bus invariants). Plus mosquitto-backed integration tests in `.github/workflows/mqtt-integration.yml`, criterion benchmarks beating every ADR target by 1.6×–208×, and an ESP32-S3 hardware validation harness (`scripts/validate-esp32-mqtt.sh`) that asserts the full pipeline end-to-end with a witness bundle generator (`scripts/witness-adr-115.sh`) that self-verifies. See [`docs/releases/v0.7.0-mqtt-matter.md`](docs/releases/v0.7.0-mqtt-matter.md), [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md), [`docs/integrations/semantic-primitives-metrics.md`](docs/integrations/semantic-primitives-metrics.md), [`docs/integrations/benchmarks.md`](docs/integrations/benchmarks.md), [`docs/adr/ADR-115-home-assistant-integration.md`](docs/adr/ADR-115-home-assistant-integration.md), tracking issue [#776](https://github.com/ruvnet/RuView/issues/776), PR [#778](https://github.com/ruvnet/RuView/pull/778). Matter SDK wiring (P8b) and CSA-certification path (P10) deferred to v0.7.1+ per ADR §9.10. Try it: `cargo run -p wifi-densepose-sensing-server --features mqtt --example mqtt_publisher -- --mqtt --mqtt-host 127.0.0.1`. - **Real-time CSI introspection / low-latency tap on `wifi-densepose-sensing-server` (ADR-099).** New `wifi_densepose_sensing_server::introspection` module wires diff --git a/docs/releases/v0.7.0-mqtt-matter.md b/docs/releases/v0.7.0-mqtt-matter.md new file mode 100644 index 00000000..fde5cc4f --- /dev/null +++ b/docs/releases/v0.7.0-mqtt-matter.md @@ -0,0 +1,104 @@ +# 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 ` | 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).