Phase 5 exit: every injected fault and every hostile manifest recovers or ends typed

[ramesh130]

Closes #184

PRD.md Part 4's Phase 5 criterion — every injected fault either recovers or produces a typed,
actionable error. Zero unclassified errors — as three tests and one added count, plus the honest
list of what still cannot recover.

1. The fault sweep — superplayer-resilience/…/FaultSweepTest.kt

Every FaultScript fault kind, under HLS and DASH, on a player a consumer builds (a profile and
Resilience.standard(), one source, no HeaderProvider). The kinds are read off
FaultScript.Builder by reflection, so a kind added later is visibly missing rather than
silently unswept. Twenty sessions, all twenty recovered or ended named, none unclassified, none
stalled:

fault kind	HLS	DASH
addLatencyMs	RECOVERED	RECOVERED
capThroughputBps	RECOVERED	RECOVERED
failWithHttpStatus (500)	typed Transient.Network	typed Transient.Network
truncateAfterBytes	typed Transient.Network	RECOVERED
failDnsResolution	typed Transient.Network	typed Transient.Network
failTlsHandshake	typed Transient.Network	typed Transient.Network
resetConnection	typed Transient.Network	typed Transient.Network
timeOutConnection	typed Transient.Network	typed Transient.Network
expireTokenAtSegment (not refreshable)	typed Transient.CdnEdge	typed Transient.CdnEdge
serveThroughCache (VOD manifest)	RECOVERED	RECOVERED

The one asymmetry is Media3's answer rather than the ladder's: a truncated HLS segment is a failed
load, while the fragmented-MP4 extractor reads the truncated DASH segment's opening boxes, finds no
samples and moves on to the next one. Recorded rather than evened out — the criterion asks that each
end recovered or named, and each does.

2. The hostile corpus, re-recorded — and why the diff is empty

Where it had to go. HostileManifestCorpusTest is superplayer-testkit's, and a phase 2 module
may not depend on a phase 5 one (docs/modules.md), so the ladder cannot be installed in that file
at all. The ladder record is therefore a second table, HostileManifestLadderTest.WITH_LADDER in
superplayer-resilience, and both tables are taken by one observer —
HostileObservation.observe, moved into testkit's main sources — so the only difference between
them is the PlaybackResilience argument.

Row by row: nothing moved. All 15 rows of WITH_LADDER equal RECORDED, and RECORDED and
GRADED are unchanged row for row. That is a finding, not a shortfall: every corpus entry is a
manifest that lies about media the origin then serves perfectly, so no load fails and the ladder is
never asked a question. The two named rows are core's own detection (ADR-0011 rule 4) reaching rung 6
with the likely cause still on them — hls-cached-live-playlist (StaleLivePlaylistException,
intermediary cache) and dash-short-time-shift-buffer-depth (LiveWindowTooShortException). The
corpus that does move the ladder is the injected one, above; PRD.md Part 4 asks for both because
they are different kinds of defect.

isTyped did need SuperPlayerError. #183 made it rung 6's cause, and a session named that way
is named exactly as the criterion asks, so it joins StaleLivePlaylistException and
LiveWindowTooShortException in FAILS_TYPED. It moves no core-only row — a player without
resilience produces none — which is one more count of rule 14.

3. What still cannot recover

One entry, recorded in CANNOT_RECOVER with its reason rather than hidden:

• dash-availability-start-time-skew — NEVER_STARTS. An availabilityStartTime an hour ahead
  of the clock means every segment the manifest names is legitimately not published yet, so the
  player waits, correctly, for ever. No load fails: there is nothing to retry, no other host to ask,
  and no failure to classify. Diagnosing it needs a doctor reading a manifest against a clock
  (PRD.md §3.6's MediaSourceDoctor, Phase 9), not a rung reading a failure.

nothingListedAsBeyondTheLadderIsQuietlyPassing keeps that list honest in the other direction: an
entry that starts recovering must leave the list. And noEntryEndsOnAFailureNothingNamed holds for
every entry without exception — a player with the module never ends a session on an unclassified
PlaybackException.

Proposed follow-up issue (not filed): Diagnose a manifest whose media is not published yet —
give Phase 9's doctor the availability-window check, so a session that will never start says so
instead of spinning. Also worth a line in that issue: today the library has no way to report
"waiting, and here is why", since rung 6 exists only for failures.

4. Every rung has a forcing test, named in one place

FallbackRungCoverageTest names, per FallbackRung, the test that forces that rung and the test
that counts what a player built without resilience pays for it:

rung	forced by	rule 14 counted by
RETRY_SAME_URL	RetryPlaybackTest.aFaultThatRelentsIsRetriedAndPlaybackGoesOn	…KeepsMedia3SOwnLoadErrorHandling
NEXT_HOST	FallbackPlaybackTest.aLocationThatFailsEveryAttemptIsLeftForTheOneTheManifestAlsoNames	…IsLeftToMedia3SOwnFallbackTable
EXCLUDE_VARIANT	FallbackPlaybackTest.aRenditionThatKeepsFailingIsExcludedAndPlaybackGoesOnAtAnotherBitrate	…IsLeftToMedia3SOwnFallbackTable
NEXT_SOURCE	NextSourcePlaybackTest.aSourceThatFailsEveryRungBelowIsLeftForTheNextOneInTheRequest	…OpensTheFirstSourceAndNothingElse
RECREATE_DECODER	core's SuperPlayerDecoderRecreationTest.aFailureTheLadderAnswersWithARecreatedDecoderIsRePreparedAndPlaysOn	…RePreparesNothing
TYPED_ERROR	TypedErrorPlaybackTest.aSessionNothingRescuedEndsOnATypedError	…EndsOnMedia3sOwnErrorUnchanged

They are names rather than code because rungs 4 and 5 are forced in superplayer-core, whose test
classes are not on this module's test classpath. The names are checked against the source tree (the
file exists; the method is declared with a @Test above it and no declaration in between), following
superplayer-abr's NoDeviceModelStringTest. A rename, a method demoted from @Test, or a seventh
rung added with no entry fails there rather than leaving a rung silently unforced.

5. Rule 14, counted

• Third slot — SuperPlayerResilienceSeamTest now asserts EngineConfiguration.playerStateRungs
  is null on a core-only player and non-null on one with resilience. That is the slot whose emptiness
  rule 14 rests on since Fallback ladder rung 4: the next source in MediaRequest.sources, at the position already reached #181: core registers its player-error listener only where it is filled, so
  an empty slot is a listener that does not exist. The test's KDoc, written before the slot existed,
  claimed there was nothing to register; it now says what is registered and where the behaviour half
  is counted.
• Load errors / header refresh — both already asserted empty there;
  DefaultLoadErrorHandlingPolicy in force is counted as behaviour in
  RetryPlaybackTest.aPlayerWithoutResilienceKeepsMedia3SOwnLoadErrorHandling.
• PlaybackFailure.classification null — TypedErrorPlaybackTest
onAPlayerWithoutResilienceTelemetryReportsExactlyWhatItReportedBefore (Rung 6: surface a typed, actionable error, and let telemetry report the classification #183).
• Core-only golden traces — the four traces in superplayer-telemetry/src/test/golden/ are
  unchanged; ./gradlew updateGoldenTraces was not run, and nothing in the diff touches them.

Review

Standards. Clean-room: no algorithm added; the one heuristic (finding a @Test above a
declaration) is documented where it lives. ADR-0011: the sweep and both corpus tables drive the
library through its public API only, and the new testkit API names no Media3 type — updateApiSurface
run, diff committed (HostileObservation, HostileOutcome). docs/modules.md's direction is
respected, and is the reason the ladder record is where it is. Smells considered: the shared observer
exists precisely to avoid Duplicated Code across two modules; FallbackRungCoverageTest's
string-named tests are a deliberate trade (a reflective form is impossible across module test
classpaths) and are validated rather than trusted; HostileObservation.STEP_MS and READY_WINDOW_MS
are public though only the enum's KDoc and the corpus's bound read them — kept public because a
reader of either table needs the window's width to read it.

Spec. All six acceptance criteria are met, with one deviation stated rather than glossed: "…
recorded tables are regenerated with the ladder in place" could not be done inside
HostileManifestCorpusTest for the module-phase reason above; the tables were re-run (unchanged) and
the ladder's record is the sibling table, with docs/testing.md updated to say a new pathology now
gets a row in three tables rather than two.

What was run, and what was skipped

./gradlew assemble check green (≈40 s cold). The three new test classes cost about 5 s together —
the harness's fake clock makes 20 swept sessions and 15 corpus entries cheap, so check can afford
them. Emulator and demo runs skipped (host memory), as the batch instructed; nothing here touches
runtime code, only tests, one test-support file and docs.

CI: https://github.com/ramesh130/superplayer/actions/runs/35069057888 — success (dispatched on issue-184-phase-exit;
.github/workflows/ci.yml is workflow_dispatch: only, so nothing runs on the PR itself).

🤖 Generated with Claude Code

https://claude.ai/code/session_01HeTWwmK1KcFMrfSAre23GS