[GLinnik21]

Second PR of the playback-refusal series (#918). It is stacked on #1054 (S0); the diff shown is S1a only.

A play the TV refuses before its first picture is now rescued by one registered state machine, OpenRecovery, which replaces the open_failure_action decision function. A manual-quality DTS play refused with num=601 (#695) now retries with the server converting the DTS track, instead of ending on the error screen.

Closes #1045

The machine

rust-modules/media/src/player/recovery.rs, registered in ci/machines.ini. player/pump.rs drives it (drive_open_recovery), and engine.rs steps LoadStarted. Each play request owns one machine on PlaybackSession. It holds the request's capability value from #1054 (start, and attempt derived from it). It reads no global and performs no IO; the driver runs its effects through the existing flight dispatch.

• States: Opening, Confirming, Flight{rung}, Playing, Failed.
• Events: Refused{refusal, facts}, RefusalConfirmed{newly}, FlightLanded, FlightRefused, FirstPicture, LoadStarted.
• Effects: ConfirmRefusal, Rollback, ConvertFacet{facet, flight}, StartAutoHls, ShowError{refusal}.
• LoadRefusal (Refused{num}, TimedOut, Stalled, SourceFailed) is the event payload and the read-out's cause.

The ladder, for a refusal before the refusing Engine's first picture:

1. Roll back a pending HLS→Original trial. This is main's first arm. It is not counted as a flight, and it narrows the attempt by a native-audio refusal it just learned.
2. Forced Direct Play goes to the error read-out.
3. Audio facet rung: when the refused stream's audio is not AAC, AC3 or E-AC3, re-plan with that audio excluded (start.without(audio)), and the server converts it (dispatch_refusal_conversion). It runs once, and only if excluding the audio actually narrows start. Audio: per-TV Opus limits, and formats the player learns to avoid #1034's Opus conversion is this rung's Opus case.
4. Both-facets rung: Auto starts the retained HLS bootstrap (main's arm); manual waits for A play refused before its first picture because of its video is retried with the video converted #1059.
5. Error read-out.

At most MAX_RECOVERY_FLIGHTS = 2 flights per request. SourceFailed and TimedOut keep main's arms. RefusalConfirmed{newly} only decides whether the install preference is written; it never picks the rung.

Behaviour changes from main

• A manual-quality play refused with num=601 (or any refusal) whose audio is DTS, TrueHD, Opus or similar retries once with that audio converted. On main it ended on the error screen.
• An Auto play whose Original is watched, with such audio, converts the audio before falling back to full HLS.
• Fixed: a native-audio stall of a combination the install had already learned left the viewer on "Buffering…" forever. It now ends on the read-out. Found on the webOS 4.5 dev set.
• Fixed: a refused foreground-resume Load was handled twice: the pump raised the error read-out, then the lifecycle retried it (Playback: a foreground Load refused while the plaintext grants return is claimed again #1018). A Load call's own synchronous refusal now belongs to the foreground lifecycle alone (Engine.foreground_follows_load), and the ladder owns refusals observed after the call returned.
• After Home and a restore, a refused restored Load no longer spins on "Connecting". LoadStarted reopens a machine left in Flight or Failed. As a backstop, a refusal the machine does not handle fails the Engine, as main always did.
• A track-switch reload refused before its picture still converts (the rung is per Engine), as on main.
• After a DTS rescue, the ABR climb re-grades the Original candidate's audio against the narrowed value (regrade_original_audio), so it does not offer DTS direct play again.
• New delivery reason refusal_recovery (telemetry, PRIVACY.md).
• Debug only: plxnative-refuse601 makes the pipeline refuse the first Load of a request with num=601. It is a runtime devtrig flag and compiles out without devtriggers.

Known deviation: the conversion keeps the refused track, so #695's files play with DTS converted rather than on their AC3 sibling, which is what 0.8.0 picked. Picking the sibling on the first retry needs the item's stream list on the session; #1059 decides whether to add it. The stored refusal (S2) makes the next play pick the sibling.

Tests

• recovery.rs: pure transition tests over the machine, including a pinned outcome for every state × event pair and a fixpoint walk proving the two-flight cap.
• pump.rs hostsim rig, including:
  • a_dts_601_before_the_first_picture_converts_dts_in_one_flight (Feature Request: Support DTS/TrueHD local Transcoding #695);
  • an_auto_original_refused_on_dts_flies_the_conversion_not_hls;
  • a_refused_conversion_ends_on_the_read_out_and_keeps_the_engine;
  • the_climb_after_a_dts_rescue_plans_no_dts_direct_play;
  • a_native_audio_stall_of_a_known_combination_ends_on_the_read_out_not_the_spinner;
  • a_native_audio_refusal_on_a_reloaded_engine_after_the_first_picture_still_converts;
  • the Home/restore cases;
  • refuse601_publishes_once_per_request_after_the_load.
• app/run.rs hostsim: a_sync_refusal_of_a_foreground_resume_load_is_settled_by_the_lifecycle_alone, plus the async companion.
• plx_telemetry: delivery_reason_codes_are_closed_and_listed.

Written red-first, with the failure observed: the machine's new ladder rows, the stall, the resume-Load split, the Home/restore cases, the reloaded-Engine case, the ABR climb and the 601 trigger. The other rig tests were written after the code; a mutation of suspect() makes each of them fail for its own reason.

Crate suites on the committed tree:

• make test-crate C=plx_media: test result: ok. 1793 passed; 0 failed; 64 ignored
• make test-hostsim C=plx_media: test result: ok. 1973 passed; 0 failed; 64 ignored
• make test-crate C=app: test result: ok. 1059 passed; 0 failed
• make test-hostsim: test result: ok. 1174 passed; 0 failed
• make test-crate C=plx_platform: test result: ok. 307 passed; 0 failed
• make test-crate C=plx_telemetry: test result: ok. 329 passed; 0 failed; 1 ignored
• make check-nodef: clean.
• ci/check-deps.sh, check-module-layers, check-machine-shape (and its self-test) and check-list-caps are green.

ci/allow/* is unchanged; recovery.rs joins the workers/globals machine scope at zero sites. make check and the ARM build are left to CI.

Docs

• player/CLAUDE.md's failed-open section now describes the ladder, the per-Engine rung, LoadStarted, and who owns a refusal.
• docs/sans-io.md and the check-deps.sh header name recovery.rs.
• docs/parity-gaps.md's cold Auto Original note is updated.
• The pump and decision docs that described the old terminal arms are corrected.

🤖 Generated with Claude Code