feat(415): per-channel fault detection — server-derived health object + Problems filter #581

Merged

timothy merged 11 commits from feat/415-channel-health into main 2026-07-23 22:45:20 +02:00

Conversation 5 Commits 11 Files Changed 25

+1858 -95

timothy commented 2026-07-23 22:11:59 +02:00

Owner

Copy Link

Copy Source

Closes #415 (deferred from #72 scope item b; sibling #414 already merged as #575).

What

Adds a server-derived health object to ChannelResponseModel (list) and ChannelDetailResponseModel (detail), plus a single "Problems" rollup filter with per-fault badges in the SPA. Supersedes #72's api.channel-health-signal (raw-PlayoutCount-only) decision → new api.channel-health-object.

"health": { "status": "Problems", "faults": ["EmptyUpcoming","BrokenSource"], "playoutCount": 2, "brokenSourceItemCount": 7 }

How — built-timeline detection (Approach A)

Every fault is derived from what the scheduler has already materialized, not from per-kind config:

• Playout.BuildStatus → NeverBuilt / BuildFailed
• upcoming PlayoutItem (Finish >= now) → EmptyUpcoming; PlayoutItem → MediaItem.State ∈ {FileNotFound, Unavailable} → BrokenSource (exact per-channel attribution, no media→collection→channel join)
• PlayoutCount == 0 → NoPlayout

Because the built timeline is the same shape for all 5 PlayoutScheduleKind values, coverage is correct by construction (the #71 "shared primitive covers all variants" trap can't bite). Assessable gate: on-demand channels suppress the absence signals (NeverBuilt/EmptyUpcoming) — keyed to the owning channel's mode so mirrors of on-demand sources don't false-flag — while presence signals (BuildFailed/BrokenSource) always apply. Rollup: any fault ⇒ Problems; assessable-clean ⇒ Healthy; else Unknown (never a false verdict for an idle on-demand playout).

Server owns the rollup so the SPA and MCP read one authoritative verdict. Cost: one bounded GROUP BY PlayoutId aggregate query (no N+1), read-time (MediaItem.State flips on scan, not build).

Done-when (#415)

• Per-channel "empty schedule" signal correct for all 5 PlayoutScheduleKind values (unbuilt/on-demand → Unknown, never Healthy)
• Broken-source attribution implemented (built-timeline seam; decision recorded)
• Cost measured — single aggregate query, no N+1 (integration test + live-E2E)
• SPA filter renamed to "Problems"; willNeverPlay → hasProblems, comment updated
• docs/decisions.md (supersede) + domain-model.md + api-conventions.md + spa-conventions.md updated
• Adversarial review passed

Verification

• 1867/1867 ErsatzTV.Tests green (incl. per-PlayoutScheduleKind guard, real-SQLite repo aggregate test, mirror-of-on-demand regression tests); 24 SPA Vitest green.
• Build clean (0 errors), BOM clean, dotnet format verify clean, check:api clean, decisions_validate OK.
• Live-E2E: health serializes on list + detail DTOs; no-N+1 confirmed on a running instance.
• 6 per-task reviews + a frontier whole-branch review (caught 1 real mirror-of-on-demand bug, fixed + re-reviewed clean).
• Rebased onto current origin/main; generated artifacts byte-identical to a fresh generation.

🤖 Generated with Claude Code

Closes #415 (deferred from #72 scope item b; sibling #414 already merged as #575). ## What Adds a server-derived `health` object to `ChannelResponseModel` (list) and `ChannelDetailResponseModel` (detail), plus a single **"Problems"** rollup filter with per-fault badges in the SPA. Supersedes #72's `api.channel-health-signal` (raw-`PlayoutCount`-only) decision → new `api.channel-health-object`. ```jsonc "health": { "status": "Problems", "faults": ["EmptyUpcoming","BrokenSource"], "playoutCount": 2, "brokenSourceItemCount": 7 } ``` ## How — built-timeline detection (Approach A) Every fault is derived from what the scheduler has already **materialized**, not from per-kind config: - `Playout.BuildStatus` → `NeverBuilt` / `BuildFailed` - upcoming `PlayoutItem` (`Finish >= now`) → `EmptyUpcoming`; `PlayoutItem → MediaItem.State ∈ {FileNotFound, Unavailable}` → `BrokenSource` (exact per-channel attribution, no media→collection→channel join) - `PlayoutCount == 0` → `NoPlayout` Because the built timeline is the same shape for all 5 `PlayoutScheduleKind` values, coverage is correct **by construction** (the #71 "shared primitive covers all variants" trap can't bite). **Assessable gate:** on-demand channels suppress the *absence* signals (`NeverBuilt`/`EmptyUpcoming`) — keyed to the *owning* channel's mode so mirrors of on-demand sources don't false-flag — while *presence* signals (`BuildFailed`/`BrokenSource`) always apply. Rollup: any fault ⇒ `Problems`; assessable-clean ⇒ `Healthy`; else `Unknown` (never a false verdict for an idle on-demand playout). Server owns the rollup so the SPA **and** MCP read one authoritative verdict. Cost: one bounded `GROUP BY PlayoutId` aggregate query (no N+1), read-time (`MediaItem.State` flips on scan, not build). ## Done-when (#415) - [x] Per-channel "empty schedule" signal correct for all 5 `PlayoutScheduleKind` values (unbuilt/on-demand → `Unknown`, never `Healthy`) - [x] Broken-source attribution implemented (built-timeline seam; decision recorded) - [x] Cost measured — single aggregate query, no N+1 (integration test + live-E2E) - [x] SPA filter renamed to "Problems"; `willNeverPlay` → `hasProblems`, comment updated - [x] `docs/decisions.md` (supersede) + `domain-model.md` + `api-conventions.md` + `spa-conventions.md` updated - [x] Adversarial review passed ## Verification - **1867/1867** `ErsatzTV.Tests` green (incl. per-`PlayoutScheduleKind` guard, real-SQLite repo aggregate test, mirror-of-on-demand regression tests); **24** SPA Vitest green. - Build clean (0 errors), BOM clean, `dotnet format` verify clean, `check:api` clean, `decisions_validate` OK. - Live-E2E: `health` serializes on list + detail DTOs; no-N+1 confirmed on a running instance. - 6 per-task reviews + a frontier whole-branch review (caught 1 real mirror-of-on-demand bug, fixed + re-reviewed clean). - Rebased onto current `origin/main`; generated artifacts byte-identical to a fresh generation. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

timothy added 10 commits 2026-07-23 22:11:59 +02:00

docs(415): design spec for per-channel fault detection (built-timeline approach) ... 99433876fd

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(415): implementation plan + refine assessable gate (presence vs absence signals) ... 524534573e

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(415): correct plan test harness (ErsatzTV.Tests + InMemoryTvContext) ... 173cecfaa4

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(415): pure channel-health derivation + health DTO b15a77ee74

feat(415): upcoming-item aggregate query + BuildStatus includes c656f4db51

feat(415): populate Health on channel list + detail DTOs ... 26ec5b5b0c

Thread the Task 2 upcoming-item aggregate through Mapper.ProjectToResponseModel
and ProjectToDetailResponseModel, add a trailing Health field to
ChannelResponseModel/ChannelDetailResponseModel, and update both API handlers
to fetch contributing-playout ids, call GetPlayoutUpcomingHealth, and pass the
result into the mapper. Regenerate the OpenAPI spec + fixture DTOs affected by
the additive field.

chore(415): regenerate OpenAPI + TS types for channel health 98ebb4df0b

feat(415): SPA Problems filter + per-fault channel badges ee82797e45

docs(415): channel health taxonomy (supersede api.channel-health-signal + conventions) 2ed1698bb2

fix(415): key on-demand suppression to owning channel (mirror-of-on-demand) + review cleanups 6c90e7caf7

timothy commented 2026-07-23 22:13:28 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 6c90e7caf7

Independent frontier whole-branch review completed; its one substantive finding (mirror-of-on-demand false Problems — suppression must key off the owning channel's mode) was fixed and re-reviewed clean, along with 4 minor cleanups. The rebase onto current origin/main changed only the docs/decisions.md conflict resolution (kept both main's #434/#435 records and this PR's supersession) and regenerated artifacts (byte-identical to a fresh generation); all reviewed C# is unchanged. Local gate green on this head: 1867/1867 ErsatzTV.Tests, build 0 errors, BOM clean, dotnet format verify clean, check:api clean, decisions_validate OK. Awaiting CI (runs 1048/1049) before merge.

Review-verdict: **MERGEABLE** @ 6c90e7caf7a116686a3c371eadc4a73f898aa975 Independent frontier whole-branch review completed; its one substantive finding (mirror-of-on-demand false `Problems` — suppression must key off the *owning* channel's mode) was fixed and re-reviewed clean, along with 4 minor cleanups. The rebase onto current `origin/main` changed only the `docs/decisions.md` conflict resolution (kept both main's #434/#435 records and this PR's supersession) and regenerated artifacts (byte-identical to a fresh generation); all reviewed C# is unchanged. Local gate green on this head: 1867/1867 `ErsatzTV.Tests`, build 0 errors, BOM clean, `dotnet format` verify clean, `check:api` clean, `decisions_validate` OK. Awaiting CI (runs 1048/1049) before merge.

timothy added 1 commit 2026-07-23 22:18:47 +02:00

fix(415): keep archived api.channel-health-signal rationale verbatim ... 4f028120d3

The supersession appended a 'Why superseded' note to the archived #72 record, which
the diff-mode decisions validator (CI 'decisions lifecycle' job) flags as a rationale-prose
change requiring [decisions-edit]. The archive's own rule is rationale-kept-verbatim, and the
'why' is already carried by the superseded-by link, the Mechanics forwarding pointer, the
archive header, and the successor record api.channel-health-object. Drop the note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

timothy commented 2026-07-23 22:18:59 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 4f02812

(Note: an earlier CI run's decisions-lifecycle job failed on 6c90e7ca — reproduced locally in diff mode, so not the known flake — and was fixed in 4f028120 by keeping the archived rationale verbatim. All checks now pass on this head.)

Review-verdict: MERGEABLE @ 4f02812 (Note: an earlier CI run's decisions-lifecycle job failed on 6c90e7ca — reproduced locally in diff mode, so not the known flake — and was fixed in 4f028120 by keeping the archived rationale verbatim. All checks now pass on this head.)

timothy referenced this pull request 2026-07-23 22:20:43 +02:00

Per-channel fault detection beyond "no playout" (empty schedule, broken source) #415

timothy commented 2026-07-23 22:21:28 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 4f02812

(Plain-format re-post of the verdict on the current head — the prior comment used markdown bold on the token. All findings resolved: the frontier whole-branch review's one substantive bug (mirror-of-on-demand false Problems) fixed + re-reviewed clean; the diff-mode decisions-validator failure fixed in 4f028120. Local gate green: 1867/1867 tests, build clean, BOM clean, dotnet format clean, check:api clean, decisions-validate OK (diff mode), catalog up to date.)

Review-verdict: MERGEABLE @ 4f02812 (Plain-format re-post of the verdict on the current head — the prior comment used markdown bold on the token. All findings resolved: the frontier whole-branch review's one substantive bug (mirror-of-on-demand false Problems) fixed + re-reviewed clean; the diff-mode decisions-validator failure fixed in 4f028120. Local gate green: 1867/1867 tests, build clean, BOM clean, dotnet format clean, check:api clean, decisions-validate OK (diff mode), catalog up to date.)

timothy commented 2026-07-23 22:23:05 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 4f02812

Review-verdict: MERGEABLE @ 4f02812

timothy commented 2026-07-23 22:24:30 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 4f028120d3

Review-verdict: MERGEABLE @ 4f028120d33287ade98a7f35095f31786dd14505

timothy merged commit 65c0e09179 into main 2026-07-23 22:45:20 +02:00

timothy referenced this issue from a commit 2026-07-23 22:45:21 +02:00

feat(415): per-channel fault detection — server-derived health object + Problems filter (#581)

timothy referenced this pull request 2026-07-23 22:45:51 +02:00

Per-channel fault detection beyond "no playout" (empty schedule, broken source) #415

timothy referenced this pull request 2026-07-23 22:56:44 +02:00

flaky: LibrariesScreen "stops scan polling and refreshes sources once when scans complete" still non-deterministic (#512 fix incomplete) #582

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

ad-hoc

One-off / ad-hoc work not tracked by a dedicated issue

api

REST API / HTTP endpoints

bug

Something isn't working

ci-cd

Build, test, deploy pipeline

content

Channel content / schedules / playlists

dependencies

Dependency updates (Renovate)

enhancement

New feature or improvement

frontend

ChicoryTV React SPA frontend

in-progress

Claimed by an active session — do not pick up

jellyfin

Jellyfin tuner / IPTV integration

parked

Excluded from automatic queue pickup; work only when explicitly selected

priority: high

priority: low

priority: medium

review

Adversarial review finding

security

Security / vulnerability fix

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

renovate timothy (Timothy)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: timothy/ersatztv#581