docs/adr/ADR-116-cog-ha-matter-seed.md
cog-ha-matter)| Field | Value |
|---|---|
| Status | Proposed — P1 research complete (docs/research/ADR-116-ha-matter-cog-research.md). P2 cog scaffold compiles (v2/crates/cog-ha-matter, 2/2 unit tests green). |
| Date | 2026-05-23 |
| Deciders | ruv |
| Codename | HA-COG — HA + Matter, packaged for the Seed |
| Relates to | ADR-110 (C6 firmware substrate), ADR-115 (HA-DISCO + HA-MIND + HA-FABRIC), ADR-102 (cog catalog), ADR-101 (cog packaging precedent) |
| Tracking issue | TBD — file under RuView issue tracker once research dossier lands |
ADR-115 shipped the Home Assistant + Matter integration as a --mqtt flag on wifi-densepose-sensing-server — a Rust binary that runs on a Pi / Linux box, consumes UDP frames from the ESP32 fleet, and publishes MQTT for any Home Assistant install to discover. That works, but it makes HA+Matter a configuration of the aggregator, not an installable artifact a Cognitum Seed user can drop into their existing fleet.
The Cognitum Seed already has a 105-cog catalog — packaged Seed apps (cog-pose-estimation, cog-quantum-vitals, cog-person-matching, etc.) that anyone can install from app-registry.json. There is no cog-ha-matter yet. That's the gap this ADR closes.
The cog packaging precedent is ADR-101 (cog-pose-estimation) which ships signed aarch64 + x86_64 binaries on GCS with a pose_v1.safetensors weight blob — same shape we'd want for the HA cog.
| Path | Distribution | Discovery | Update | Witness | Local AI |
|---|---|---|---|---|---|
--mqtt on sensing-server | manual install of the Rust binary | none | manual | none | external |
cog-ha-matter Seed cog | app-registry.json listing, one-click install | mDNS / cog browser | OTA via cog runtime | Ed25519 witness chain | local ruvllm + RuVector |
The cog ships HA+Matter as a first-class Seed feature — same UX as installing a pose estimator or person matcher.
--mqtt flag on sensing-server. The flag stays for Pi / Linux deployments without a Seed; the cog is the Seed-native option.Build cog-ha-matter as a Cognitum Seed cog with these surfaces:
The cog republishes the same 21 entities per node (11 raw + 10 semantic primitives) over MQTT auto-discovery, so HA installations behave identically whether the source is a Seed cog or an external sensing-server.
cognitum-seed.local:1883 and act as the HA endpoint directly._ruview-ha._tcp so HA's discovery integration finds the Seed without manual config.semantic-thresholds.yaml, the cog learns per-home thresholds via a SONA-adapted RuVector model (matches the Seed's local-first AI story).The research dossier covers (a) Matter Bridge vs Matter Device mode, (b) Thread Border Router on the Seed's ESP32-S3 (if feasible), (c) CSA certification path, (d) which Matter device classes map cleanly to which entities. Decision deferred until the dossier lands; this ADR will be updated in §3 with the specific Matter feature set.
Multiple Seeds in adjacent rooms coordinate via:
The federation model is the natural extension of ADR-110's mesh substrate into the application layer. Specifically: ADR-110 gives us ≤100 µs cross-board sync; this ADR uses that to deduplicate cross-Seed events (one fall, one alert) and reconstruct multi-room transitions (one occupant, room A → hallway → room B).
Full dossier: docs/research/ADR-116-ha-matter-cog-research.md. The eight research questions are now answered:
OccupancySensor (0x0107) with RFSensing feature flag on cluster 0x0406 (revision 5 in Matter 1.4). That's the correct device class for WiFi-CSI sensing — no health/vitals cluster exists in Matter 1.4.2 and won't soon. Seed acts as Bridge with N dynamic OccupancySensor endpoints, not Commissioner (the C6 sensing nodes stay Accessories only — 320 KB SRAM no PSRAM rules out commissioning).CONFIG_OPENTHREAD_BORDER_ROUTER=y is the only config step. ADR-110's c6_timesync.c already initialises 802.15.4 — TBR is a Kconfig flag away. Real value: HA's Improv-style commissioning works without a separate Thread border router box.set_privacy_mode, calibrate_zone), i18n translations. Bronze is the minimum bar; Gold (repairs + diagnostics + reconfiguration) is the target. Start from hacs.integration_blueprint template.network.mqtt + network.matter + api.ruview_vitals.ruvllm-esp32 v0.3.3 confirms SONA self-optimising adaptation under 100 µs per query. 8→10 INT8 classifier ~10 KB quantised. Per-home threshold tuning via HA thumbs-up/thumbs-down feedback as LoRA-style gradient steps — closes the top user complaint (false positives) without cloud round-trips.--privacy-mode audit-only tier (no MQTT state messages, only SHA-256 digests on-Seed) creates a technical PHI barrier. OccupancySensor (0x0107) device class keeps the product in the same regulatory category as a smart motion sensor.Ranked by build cost × user impact:
| # | Feature | Cost | Impact | Phase |
|---|---|---|---|---|
| 1 | --privacy-mode audit-only tier (no MQTT state, SHA-256 digests on-Seed) | ~1 week | Closes care / GDPR deployments | P3 (this cog) |
| 2 | Seed cog manifest + Ed25519 signing + store listing | ~1-2 weeks | Enables one-click distribution | P2 + P8 (this cog) |
| 3 | Local SONA fine-tuning loop (HA feedback → LoRA gradient steps) | ~2-3 weeks | Reduces false positives, closes #1 user complaint | P5 (this cog) |
| 4 | HACS gold-tier integration (config flow + repairs + diagnostics) | ~4-6 weeks | Removes MQTT prerequisite for mainstream users | P9 (separate repo hass-wifi-densepose) |
| 5 | Matter Bridge with OccupancySensor + dynamic endpoints | ~6-8 weeks | Apple Home / Google Home / Alexa native | v0.8 dedicated sprint (after HACS adoption data) |
| 6 | Embedded MQTT broker (rumqttd) inside the cog | ~1 week | "Works without external broker" but every HA install already has mosquitto / built-in | v0.7 deferred — adds ~2 MB binary + ACL config surface for marginal user benefit. Dossier ranking did not include this in the prioritised v1 scope. |
| Phase | Scope | Status |
|---|---|---|
| P1 | Research dossier (docs/research/ADR-116-ha-matter-cog-research.md) | ✅ done — 8 sections, 30+ citations, v1 scope ranked |
| P2 | Cog crate scaffold (v2/crates/cog-ha-matter/) — Cargo.toml + src/{lib,main,manifest}.rs, workspace member, CLI args, --print-manifest flag, 2 manifest unit tests | ✅ done — cargo check + cargo test green |
| P3 | Wrap existing ADR-115 MQTT publisher as cog entry point | ✅ wiring done — main.rs boots ADR-115's publisher::spawn via runtime::spawn_publisher thin wrapper, holds a long-lived broadcast::Sender<VitalsSnapshot>, awaits Ctrl-C. Live-handle test green without a broker. Next (P3.5): subscribe to sensing-server /v1/snapshot WS and republish into the channel. |
| P4 | Seed-native enhancements (mDNS, witness; embedded broker deferred) | ✅ shipped — mDNS half: record-builder + ServiceInfo conversion + live responder wired into main.rs (HA auto-discovery on _ruview-ha._tcp works out of the box, --no-mdns flag for restrictive networks). Witness half: hash-chain + JSONL + file persistence + chain-level verify + Ed25519 signing. Embedded rumqttd broker deferred to v0.7 per dossier §8 ranking — not in the prioritised v1 scope; v1 ships with external-broker only (mosquitto or HA's built-in broker). See §4 v1 scope table. |
| P5 | RuVector-backed threshold learning (SONA adaptation) | pending |
| P6 | Multi-Seed federation (cross-Seed dedup + witness) | pending |
| P7 | Matter Bridge mode (depends on matter-rs / esp-matter readiness) | pending |
| P8 | Cog signing + app-registry.json listing + Seed Store entry | pending |
| P9 | HACS integration repo (hass-wifi-densepose) for HA-side install path | pending |
| P10 | Witness bundle + CSA-style spec compliance check | pending |
cog-pose-estimation packaging precedent (signed binaries on GCS, .cog manifest)app-registry.json surfaces all cogs)docs/research/ADR-116-ha-matter-cog-research.md — companion research dossier (deep-researcher agent in progress)