---
key: api.healthcheck-remediation-dto
title: 2026-07-17 — Health-check remediation is server-declared `{Kind, Target}` on an additive DTO; the SPA acts on it (#164)
status: active
since: '2026-07-17'
supersedes: none
superseded-by: none
rule: Health-check remediation is server-declared `{Kind, Target}` metadata on an additive DTO field; the SPA renders/acts on it, it doesn't derive labels itself.
signals: 'health checks, remediation, AppRoute/ExternalDoc · paths: `HealthCheckResponseModel`, `HealthCheckLink` · issues: #164, #286, #108'
mechanics: '`HealthCheckResponseModel.Remediation`; Application `Mapper.GetStatus`'
---

#164 asked to make the ~14 health checks *actionable* — the Dashboard health panel showed problems
with no way to investigate or fix them. Two structural decisions came out of it.

**Remediation is server-declared metadata, not SPA-derived.** Each check that has a fix knows where the
fix lives, so the *check* declares it. The domain `HealthCheckLink` grew from `(string Link)` to
`(string Target, HealthCheckLinkKind Kind)` with `Kind ∈ {ExternalDoc, AppRoute}` and two factories
(`HealthCheckLink.ExternalDoc(url)` / `HealthCheckLink.AppRoute("/app/...")`). Only the 4 checks that
built links and the API mapper touched `.Link`, so the widening was local. The SPA then *acts* on the
kind: `AppRoute` → client-side `navigateToPath(target)` button; `ExternalDoc` → new-tab anchor. The
human label is derived SPA-side from the route (a small lookup + prettified fallback) rather than sent
over the wire — keeping the DTO minimal.

**The DTO evolved additively (`/api/v1` is frozen-additive, #286).** `HealthCheckResponseModel` kept
its existing `Detail` and gained `Brief` (← the domain `BriefMessage` the old mapper silently dropped)
and `Remediation { Kind, Target }` (a nested `HealthCheckRemediationResponseModel`). The old flat
`string? Link` is **kept and still populated** (mirrors `Remediation.Target`) but documented deprecated —
we don't remove a frozen field, and existing consumers keep working. `Remediation.Kind` is a plain
string ("ExternalDoc"/"AppRoute") mapped in the Application `Mapper` exactly like `Status`
("pass"/"fail"/…), not a wire enum — matching the established pattern for that DTO.

**Three defects the audit surfaced, fixed here.** (1) The Application `Mapper.GetStatus` threw
`ArgumentOutOfRangeException` on `NotApplicable`; the handler filters `NotApplicable` before mapping so
it was latent, but the mapper is now **total** (defense-in-depth — a future caller that skips the filter
can't 500 the endpoint). `InternalsVisibleTo("ErsatzTV.Tests")` was added to the Application assembly
(mirroring Core's precedent) to unit-test that totality directly. (2) Two checks linked to **stale
Blazor routes** (`media/trash`, `search?query=…`) — repointed to the SPA `/app/trash` and
`/app/search?query=…` as `AppRoute`s. (3) A dead `Open Classic UI` → `/system/health` link lingered in
`SettingsScreen` (a #91b leftover that just 302'd to `/app`); removed (see `blazor-route-parity.md`
Section 4 correction).

**Actionable checks that had no link gained an `AppRoute`** (metadata → `/app/libraries`, empty
schedules → `/app/schedules`, HW-accel / VAAPI → `/app/ffmpeg-profiles`, FFmpeg reports → `/app/settings`).
Pure-noise / no-clean-action checks (UnifiedDocker, MacOsConfigFolder, FFmpegCapabilities, the Info-tier
nags) were left untouched — semantic-tier changes (e.g. adding a Pass path, demoting a nag) were
deliberately **not** bundled into a remediation-UX PR.

**Deferred (own issue): a TTL cache for `PerformHealthChecks`** (#108 — every `GET /api/v1/health`
re-runs all 14 checks, 4 shelling out to ffmpeg, and the existing summary cache is write-only dead
code). Orthogonal to the UX; filed separately so a SPA-polled health panel gets a cache before it
polls.