ADR-122: BFLD RuView Surface — Home Assistant, Matter, MQTT Exposure

1. Context

ADR-115 shipped the RuView Home Assistant surface (21 entities, MQTT auto-discovery, mTLS, privacy mode) on the wifi-densepose-sensing-server Rust binary. ADR-116 is packaging this as the cog-ha-matter Cognitum Seed cog. BFLD must integrate into this surface without expanding the privacy-sensitive footprint already in production.

The integration must:

1. Extend HA-DISCO to advertise BFLD entities via the existing MQTT-discovery scheme.
2. Reject identity fields at the Matter boundary — Matter exposes occupancy/motion/people-count only, never identity_risk_score or rf_signature_hash.
3. Route MQTT topics by privacy class — class-2/3 events on the public topic tree, class-1 events on a gated research/ subtree, class-0 events nowhere.
4. Federate cleanly into cognitum-v0 — BFLD events from multiple nodes flow through cognitum-rvf-agent (port 9004 per CLAUDE.local.md) for cross-node analytics, but identity-derived fields are stripped at the publishing-node boundary, not at the federation hub.

2. Decision

2.1 HA entity surface (six new entities per node)

The cog republishes the existing 21 ADR-115 entities and adds:

The identity_risk entity is exposed only under privacy class 2 and is flagged entity_category: diagnostic so HA dashboards do not promote it to a main-card sensor by default. Under class 3 it is computed but not published (per ADR-121 §2.4).

MQTT discovery payload follows the ADR-115 schema, plus a bfld_version attribute matching the BfldFrameHeader::version field.

2.2 MQTT topic tree

ruview/<node_id>/bfld/presence/state              # class >= 2
ruview/<node_id>/bfld/motion/state                # class >= 2
ruview/<node_id>/bfld/person_count/state          # class >= 2
ruview/<node_id>/bfld/zone_activity/state         # class >= 2
ruview/<node_id>/bfld/confidence/state            # class >= 2
ruview/<node_id>/bfld/identity_risk/state         # class == 2 only
ruview/<node_id>/bfld/raw                         # class 1, OFF by default
ruview/<node_id>/bfld/availability                # online/offline marker

raw (class-1 derived BFI) is not present in the discovery payload at all — operators must explicitly subscribe and acknowledge the research-mode caveat. The publishing crate emits MQTT_RAW_DISABLED to availability when privacy_class < 1.

2.3 Mosquitto ACL example

# Default-deny everything not explicitly granted
pattern read  ruview/+/bfld/+/state
pattern read  ruview/+/bfld/availability

# Public roles cannot read identity_risk or raw
user public
deny  read ruview/+/bfld/identity_risk/state
deny  read ruview/+/bfld/raw

# Operator role can read identity_risk for diagnostics
user operator
allow read ruview/+/bfld/identity_risk/state

# Research role can read raw (requires class-1 operation)
user research
allow read ruview/+/bfld/raw

The cog ships a default ACL template under cog-ha-matter/etc/mosquitto.acl.d/bfld.conf for operators who use the embedded broker (ADR-116 §2.2).

2.4 Matter cluster boundary

cog-ha-matter exposes BFLD via three Matter clusters only:

Explicitly NOT exposed via Matter:

• identity_risk_score
• rf_signature_hash
• identity_embedding
• raw BFI
• zone_activity (zone IDs are site-specific and Matter is a cross-site surface)
• confidence (HA-only diagnostic)

The Matter filter is implemented in cog-ha-matter/src/matter/bfld_filter.rs as a MatterSink trait impl that rejects classes 0 and 1 at compile time (via ADR-120 §2.2 marker types).

2.5 Federation with cognitum-v0

cognitum-rvf-agent (port 9004) receives BFLD events from multiple nodes. The events arriving at the federation hub are already class-2/3 — identity-derived fields were stripped at each publishing node. The hub does not see and cannot reconstruct raw BFI or identity embeddings.

The federation contract:

A federation-witness script (extending ADR-028) runs nightly on the hub and proves that no class-0/1 fields appeared in any received event over the previous 24 h.

2.6 HA blueprints (shipped with the cog)

Three operator-ready blueprints under cog-ha-matter/blueprints/:

1. Presence-driven lighting — binary_sensor.*_bfld_presence ⇒ light.turn_on/off with configurable hold time.
2. Motion-aware HVAC — sensor.*_bfld_motion > 0.3 ⇒ raise HVAC setpoint by ΔT.
3. Identity-risk anomaly notification — sensor.*_bfld_identity_risk exceeds rolling z-score threshold ⇒ HA notify.* to the operator with the originating node and the 7-day baseline.

3. Consequences

Positive

• Six new HA entities give operators a complete BFLD diagnostic dashboard without leaking identity.
• Matter exposure is structurally narrow — the cluster-filter implementation cannot accidentally expose identity fields because the type system rejects them.
• The default ACL template gives operators a working privacy posture out of the box.
• The federation contract makes it explicit that the hub cannot reconstruct identity even from the union of all node events.

Negative

• The identity_risk HA entity exists only under class 2. Operators who run class 3 deployments cannot see the score even in their own dashboard. This is correct but may surprise care-home installers; documentation must be clear.
• Three Matter clusters is conservative — some HA users may want the count exposed as a percentage or rate, which Matter does not support natively.
• HA-blueprint coverage is intentionally small; operators wanting custom automations must work through the YAML surface.

Neutral

• The federation witness script runs nightly. A short-duration leak between witnesses is possible but bounded — any successful exfiltration of class-1 fields would still need to be reconstructed into identity, which the daily hash rotation breaks.

4. Alternatives Considered

Alt 1: Expose identity_risk over Matter (Generic Sensor cluster)

Rejected: Matter is a cross-vendor surface; exposing identity-risk there leaks the score to every Matter controller in the home, including third-party hubs the operator may not control. Keep it HA-internal.

Alt 2: One unified MQTT topic ruview/<node>/bfld with JSON payload

Rejected: per-entity topics are the HA-DISCO convention (ADR-115) and let ACLs be field-specific. A unified topic forces an all-or-nothing read policy.

Alt 3: Federate raw BFI to cognitum-v0 for cross-node analytics

Rejected: violates ADR-120 I1 (raw never leaves the node). Aggregates are sufficient for cross-node analytics; raw centralization is a hard no.

Alt 4: Default entity_category: diagnostic = false for identity_risk

Rejected: promoting identity_risk to a main-card sensor would surprise operators with an identity-adjacent gauge on their main dashboard. Diagnostic category is the right default.

5. Acceptance Criteria

• AC1: HA auto-discovery publishes six new entities per node on first connect; HA recognizes all six.
• AC2: Under privacy class 3, sensor.<node>_bfld_identity_risk is absent from the MQTT discovery payload.
• AC3: MatterSink::publish rejects any frame at compile time when the source has privacy_class < 2.
• AC4: The default mosquitto ACL denies read ruview/+/bfld/identity_risk/state to the public user role.
• AC5: Three HA blueprints install cleanly into a fresh HA install and trigger their configured actions against a mock BFLD event stream.
• AC6: The federation-witness script detects an injected class-1 field in a synthetic event and exits non-zero.
• AC7: Matter occupancy-sensing cluster reports presence within 1 s of an HA binary_sensor.*_bfld_presence state change.

6. References

• ADR-115 (HA-DISCO entity scheme)
• ADR-116 (cog-ha-matter cog packaging)
• ADR-120 (privacy class enforcement)
• ADR-121 (identity risk source)
• ADR-100 (cog packaging spec)
• Mosquitto ACL reference: https://mosquitto.org/man/mosquitto-conf-5.html
• Matter spec — Occupancy Sensing cluster (0x0406)
• Cognitum V0 appliance dashboard: http://cognitum-v0:9000/