# Per-Integration Gap Audit: `harmony` (Logitech Harmony Hub)

> Status legend, method, and sizing: see [`docs/03-quality-scale-audit-rubric.md`](../03-quality-scale-audit-rubric.md).
> Snapshot findings; 🔍 items must be re-verified against `dev` before implementation.

## 1. Snapshot

| Field | Value |
|---|---|
| Domain | `harmony` |
| Category | Universal remote hub (discontinued hardware, very large installed base) |
| IoT class | `local_push` (websocket to hub) |
| Backing library | `aioharmony` |
| Platforms | `remote`, `select` (current activity); legacy activity `switch` platform was deprecated/removed 🔍 |
| Custom services | `sync`, `change_channel` 🔍 |
| Declared `quality_scale` | none (unrated) |
| Code owners | Listed in `CODEOWNERS`; mix of long-standing core contributors 🔍 |
| Popularity band (M1 dataset) | High — despite Logitech discontinuing the product line, install count remains top-tier for media control |
| Issue-volume band (M1 dataset) | Medium — themes: hub reconnect after power loss, activity state desync, slow command sends |

**Why selected:** discontinued hardware means *no new feature pressure* — quality
polish is the only remaining value vector, maintainer load is low, and the large
existing user base gets pure quality-of-life gains. Risk of colliding with roadmap
work is near zero.

## 2. Architecture summary

One config entry per hub, discovered via SSDP (and historically XMPP/websocket probe).
A central `HarmonyData` wrapper owns the `aioharmony` client, exposes callbacks for
connect/disconnect/activity-change, and fans out to the `remote` entity (send
commands, turn on/off activities) and a `select` entity for current activity.
State is push-based over the hub websocket; no polling, no authentication.

## 3. Gap audit

| # | Dimension | Status | Evidence / notes |
|---|---|---|---|
| D1 | Config flow completeness | ✅ Met 🔍 | SSDP discovery + manual host; unique ID from hub ID; options flow for activity behavior (`delay_secs`, default activity). Verify rediscovery updates a moved hub's host. No reconfigure step — low priority given SSDP works on these hubs, but cheap to add for Gold track. |
| D2 | Reauth & credentials | ➖ N/A | No authentication. `exempt` with rationale. |
| D3 | Runtime data & typing | 🟡 Partial 🔍 | `HarmonyData` stored in `hass.data` at snapshot; migrate to typed `runtime_data`. Callback wiring (`HarmonyCallback` named tuples / subscriber pattern) is under-typed; tighten. Not in `.strict-typing`. |
| D4 | Update strategy | ✅ Met | Pure push with library-managed reconnect. Rubric items: verify entity availability is driven by connect/disconnect callbacks (it is, via subscriber pattern) and `PARALLEL_UPDATES` set 🔍 |
| D5 | Diagnostics & repairs | ❌ Gap | No `diagnostics.py`. Payload: hub firmware/config summary, activity list, device list (names only), connection state, redacted host. "Activity desync" reports are currently un-triageable without asking users for debug logs. |
| D6 | Entity naming & device registry | 🟡 Partial 🔍 | Device registry populated. Verify `has_entity_name` on `remote` (should be `name=None` as the primary entity) and the activity `select` (translated name). M1 sampling showed composed names. |
| D7 | Error handling & availability | 🟡 Partial | Connect failures at setup → `ConfigEntryNotReady` ✅. Gaps: reconnect storm logging after hub power loss (log once + backoff); command-send failures (`aioharmony` send errors) silently logged instead of raising translation-backed `HomeAssistantError` to the service caller. |
| D8 | Test coverage | 🟡 Partial | Good config-flow tests and a reasonable mock of `aioharmony`. Gaps: snapshot tests for entities, activity-change push-callback tests, `sync`/`change_channel` service tests, disconnect→unavailable test. |
| D9 | Documentation & strings | 🟡 Partial | Options lack `data_description`. Docs page predates the select-entity migration in places 🔍 and lacks a "hub lost power / IP changed" troubleshooting section (top issue theme). |
| D10 | Quality-scale declaration | ❌ Gap | Undeclared. Bronze fully achievable; Silver requires D7 polish + docs; both in scope. |

## 4. Detailed findings

### D7 — Failure feedback for commands (highest-impact gap)
When a command send fails (device asleep, hub busy), today's behavior is a debug-level
log and silent success from the user's perspective — automations "work" but the TV
never turns on. Plan: surface send failures as translation-backed
`HomeAssistantError` from `remote.send_command` / activity changes, with the failed
command and device in placeholders. This converts the "slow/dropped commands" issue
cluster from ghost reports into actionable errors.

### D5 — Diagnostics
The hub's config dump (activities, devices, control groups) is the key artifact for
desync triage. Include a sanitized version (IDs + names, no location metadata),
current activity per hub vs. per entity state, and websocket connection statistics.

## 5. Work items

| ID | Title | Dimensions | Effort | Depends on |
|---|---|---|---|---|
| HAR-01 | Migrate `HarmonyData` to typed `runtime_data`; tighten callback typing | D3 | M | — |
| HAR-02 | Add `diagnostics.py` (sanitized hub config, connection state) + tests | D5 | S | HAR-01 |
| HAR-03 | Translation-backed errors for failed command/activity sends; tests | D7, D8 | M | HAR-01 |
| HAR-04 | Reconnect log hygiene (warn-once + backoff-aware logging) | D7 | S | — |
| HAR-05 | `has_entity_name` migration (`remote` as primary entity) | D6 | S | — |
| HAR-06 | Snapshot + push-callback + service tests | D8 | M | HAR-05 |
| HAR-07 | Strings `data_description`; docs troubleshooting section (docs repo PR) | D9 | S | — |
| HAR-08 | Declare `quality_scale: bronze` + checklist (`reauth: exempt`) | D10 | S | HAR-02, HAR-03, HAR-06 |

Target tier: **Bronze declared, Silver-track.**

## 6. Risks & coordination notes

- HAR-03 changes observable service behavior (errors now raised). Flag prominently in
  the PR and tracking issue; code owners may prefer a warning-level log plus repair
  issue instead — accept either, the goal is non-silent failure.
- Discontinued hardware means CI mocks are the only safety net; invest in fixture
  quality (real hub config dumps are available in existing test fixtures — extend,
  don't replace).
- Verify current platform set on `dev` (the activity switch→select migration timeline) 🔍.