# Per-Integration Gap Audit: `dlna_dmr`

> 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 | `dlna_dmr` |
| Category | Generic UPnP/DLNA Digital Media Renderer (smart TVs, AVRs, speakers) |
| IoT class | `local_push` (UPnP eventing) with poll fallback |
| Backing library | `async-upnp-client` |
| Platforms | `media_player` |
| Declared `quality_scale` | none (unrated) 🔍 |
| Code owners | Library author + co-maintainer listed at snapshot 🔍 — structurally one of the healthier maintainership situations in the target set |
| Popularity band (M1 dataset) | High — generic renderer support means it silently backs a large device population, including devices with no dedicated integration |
| Issue-volume band (M1 dataset) | Medium — themes: device not re-detected after IP change, eventing failures behind firewalls (callback URL unreachable), poll-fallback confusion |

**Why selected:** this integration was substantially rewritten with modern patterns
(full config flow, SSDP, good test suite), so it is *close* to a declarable tier
already — high completion probability — and as a generic fallback integration its
quality improvements benefit a wide, heterogeneous device population.

## 2. Architecture summary

Devices are discovered over SSDP (`MediaRenderer` device type). Each entry stores the
device's UDN as unique ID and its description URL. At runtime, `async-upnp-client`
builds a `DmrDevice` profile exposing transport/rendering controls; state updates
arrive via UPnP eventing (the integration subscribes with a callback URL served by
core's UPnP event handler), with polling fallback when eventing is unavailable.
SSDP `alive`/`byebye` tracking drives availability and host updates. An options flow
controls poll-availability, callback URL override, and browse filtering. No
authentication (reauth N/A).

## 3. Gap audit

| # | Dimension | Status | Evidence / notes |
|---|---|---|---|
| D1 | Config flow completeness | ✅ Met | SSDP discovery with UDN unique ID, ignored-device handling, manual URL entry, options flow (poll availability, callback override, hide media types 🔍). Rediscovery updates description URL on UDN match. No reconfigure step needed (SSDP rediscovery covers host changes; document this). |
| D2 | Reauth & credentials | ➖ N/A | UPnP control here is unauthenticated. `exempt` with rationale. |
| D3 | Runtime data & typing | 🟡 Partial 🔍 | The integration was written with thorough annotations (library author discipline). Verify `runtime_data` adoption (rewrite predates the pattern); migrate if needed. Strong `.strict-typing` candidate — possibly already listed 🔍. |
| D4 | Update strategy | ✅ Met | Push via eventing, automatic poll fallback, SSDP-driven availability. Verify `PARALLEL_UPDATES` 🔍. No coordinator needed (rubric exemption: push-primary). |
| D5 | Diagnostics & repairs | ❌ Gap | No `diagnostics.py` at snapshot 🔍. Payload: device description summary (manufacturer, model, UDN redacted to prefix), service list, eventing vs polling mode, last SSDP seen, callback URL reachability flag. Directly addresses the eventing-failure issue cluster. Consider a **repair issue** when event subscription persistently fails and poll fallback is active ("Your network blocks UPnP eventing; state updates will be delayed") — converts silent degradation into guidance. |
| D6 | Entity naming & device registry | 🟡 Partial 🔍 | Device info from device description. Verify `has_entity_name` with `name=None` primary entity; rewrite-era code used the device friendly name as entity name. |
| D7 | Error handling & availability | ✅ Met (verify) 🔍 | Mature: `ConfigEntryNotReady` on unreachable description URL, SSDP byebye → unavailable, command errors wrapped. Audit remaining raw `UpnpError` passthroughs in `play_media`/browse paths and back them with translations. |
| D8 | Test coverage | 🟡 Partial | Config-flow and core entity behavior well tested (among the better suites in the target set). Gaps: snapshot tests, eventing-failure → poll-fallback transition test, repair-issue test (new), diagnostics test (new). |
| D9 | Documentation & strings | 🟡 Partial | Options lack `data_description` (callback URL override is cryptic without it — recurring confusion). Docs need a networking section: multicast/SSDP requirements, eventing callback reachability, VLAN guidance. |
| D10 | Quality-scale declaration | ❌ Gap | Undeclared despite being near-Silver structurally. Declare Bronze immediately after verification; Silver after D5/D9; realistic **Gold candidate** by end of program (docs depth + diagnostics + repairs + full test sweep). |

## 4. Detailed findings

### D5 — Repairs for degraded eventing (highest-impact gap)
The "state doesn't update / updates slowly" issue cluster is almost always blocked
eventing (callback URL unreachable across subnets). The integration already knows
when subscription fails and falls back to polling — it just doesn't tell the user.
Raising a fixable repair issue with a docs link (and clearing it when eventing
recovers) is a small, novel-but-pattern-conformant improvement; flag it explicitly in
the tracking issue since it adds user-visible behavior.

### D10 — Gold candidacy
Because D1/D4/D7 are already substantially met, this is the best Gold candidate in
the 12-integration set. Gold additionally demands documentation excellence
(use-cases, supported devices guidance, troubleshooting) — budget the docs PR
accordingly (it is larger than the code PRs for this integration).

## 5. Work items

| ID | Title | Dimensions | Effort | Depends on |
|---|---|---|---|---|
| DLN-01 | Verification pass: `runtime_data`, strict-typing listing, `PARALLEL_UPDATES` (fix what fails) | D3, D4 | S | — |
| DLN-02 | Add `diagnostics.py` (sanitized device description, eventing state) + tests | D5 | S | DLN-01 |
| DLN-03 | Repair issue for persistent eventing failure with poll fallback + tests | D5, D8 | M | DLN-02 |
| DLN-04 | `has_entity_name` migration | D6 | S | — |
| DLN-05 | Translation-backed errors for remaining raw `UpnpError` paths | D7 | S | — |
| DLN-06 | Snapshot tests + eventing-fallback transition test | D8 | M | DLN-04 |
| DLN-07 | Strings `data_description` (esp. callback override) + docs networking/troubleshooting section (docs repo PR) | D9 | M | — |
| DLN-08 | Declare `quality_scale: bronze` → `silver`; file Gold `todo` checklist | D10 | S | DLN-02, DLN-05, DLN-06, DLN-07 |

Target tier: **Silver declared, Gold checklist filed** (Gold completion is stretch,
dependent on owner appetite for DLN-03 and docs review bandwidth).

## 6. Risks & coordination notes

- Code owners include the library author; behavior questions (eventing retry policy)
  should be deferred to them in the tracking issue — some logic may belong upstream
  in `async-upnp-client`.
- DLN-03 introduces new user-visible behavior (repair issues). Per engagement plan
  §3.2, this requires explicit owner sign-off in the tracking issue *before* the PR,
  and conformance with the existing repairs ADR/patterns.
- Generic-renderer breadth means regressions hit heterogeneous devices; keep PRs
  minimal and rely on the existing fixture corpus, extending it with at least one
  poll-only device fixture.