Skip to content

fix(playback): keep a plan's effective row in the item's version list - #458

Closed
randrini wants to merge 3 commits into
integration/playback-combinedfrom
fix/plan-stays-in-version-list
Closed

randrini wants to merge 3 commits into
integration/playback-combinedfrom
fix/plan-stays-in-version-list

Conversation

@randrini

Copy link
Copy Markdown
Collaborator

Problem

Related issue: N/A
Validation tasks: none

Two items on the combined build could not be played, and one of the two failures also hid the reason.

A start answered requested_media_file_id=304999 with effective_media_file_id=1320729. The item had 452 version rows and 1320729 was not one of them, so progress recorded 304999 while watch state recorded 1320729 and the client had no way to reconcile what was playing with what was picked.

The item page then dead-ended: it kept the stored last_file_id as the selected row, found no matching row in the version list, and showed "Version unavailable / The selected version is no longer available" with Play disabled. A second item showed the same screen with playback_variants[0].default_file_id=416262 marked failed:true, available:false and user_data.last_file_id=1204391 absent from the list, so the page had no row it was willing to start.

POST /catalog/versions/check for a row whose bytes belong to a different release answered only available:false, failed:true. The user was told the version was unavailable rather than that the provider served a different release. One play attempt was enough to stamp that row failed: the candidate loop joins each refusal with "no usable stream", and the dead-pin classifier matched that text as a confirmed-dead pin.

This PR is stacked on integration/playback-combined and targets that branch rather than main.

Approach

A start's effective row now has to be one of the item's selectable version rows. The detail service exposes the ids from its own version-list projection (same authorization, fetch and duplicate collapse the page gets), and a start checks the resolved row against that set before planning. A row outside the set is refused like any other unusable candidate: the candidate that produced it is excluded and the walk tries the next one, and when nothing qualifies the start answers the retryable version-list terminal instead of planning a row the client cannot reconcile.

Two cases are exempt, for reasons written at the guard. The requested row itself is the client's own pick from the list it holds. A provider-neutral listing row owns no bytes, so binding it to the row that owns the served candidate is ordinary auto selection, not a substituted version; that is the one shape where the effective row is legitimately absent from the list. An unknown answer (unwired seam, lookup error, item with no version rows) fails open, so a catalog hiccup cannot refuse playable content.

The refusal that reports served bytes contradicting the row now arms the same served-vs-declared verdict the version list already renders as source_mismatch, and the start terminal carries that reason with the version-list hint. The value is additive: reason is a free-form string in the v2 contract, the version-check field already exists, and no artifact changed.

Neither refusal can indict the requested row. Both are excluded from the dead-pin classifier, which is the path that turned one attempt on a source-mismatch row into a durable failed:true.

The item page always resolves a playable row. An explicit pick made on this device is kept even when liveness reports it failed, because Play re-links that row rather than choosing another release behind the viewer's back. Every other preference (the server's last_file_id, or the server's default row) is skipped when it is failed or unavailable, and the page names the row it skipped and the row it plays instead. The shared selection lives next to the existing version-ranking helpers so the movie and episode pages cannot drift, and the player recognizes source_mismatch with the retry the server marks as available.

Validation

  • go build ./..., with the embed stub make build creates.
  • go vet on ./internal/api/handlers, ./internal/catalog, ./internal/apiv2, ./internal/playback: clean.
  • go test -count=1 ./internal/apiv2 ./internal/catalog: pass.
  • go test -count=1 ./internal/api/handlers: pass except TestHandleStartPlaybackV3ReturnsBoundedOnSlowProbe and TestHandleStartPlaybackV3DoesNotWaitForSessionSync. Both are wall-clock assertions (40 ms and 1 s) that fail identically on the base commit in this arm64 test container; verified by stashing the branch's Go changes and re-running them.
  • go test -count=1 ./internal/playback: three tests fail in this container while generating or measuring ffmpeg fixtures (TestResolveCopySeekAnchorMatchesRealLongGOPHEVC reports signal: killed from fixture generation, plus TestOnDemandSubtitleSegmentsDoNotWaitForTheStream and TestServeExtractDiscardsACappedDemuxCopy). This branch does not change that package.
  • go test -race on the new handlers tests: pass.
  • make verify-playback-fixtures and make verify-apiv2-openapi: current. The wire shape did not change.
  • scripts/check-fork-invariants.sh: fork invariants hold.
  • scripts/lint-changed.sh with BASE_REF=integration/playback-combined, run inside the repository's build container: 0 issues.
  • Web: 42 test files and 449 tests covering the item page, version ranking, version liveness, version health and player error copy. Prettier and ESLint clean on the touched files.
  • No attached media.

Risks

Behavior change: a start that used to plan an unlisted effective row now refuses that candidate and either plays another listed row or answers a retryable terminal naming the version list. Clients that relied on the effective id to point at a duplicate row the list collapses will instead see the requested row or a clear refusal.

The version-list lookup runs only when the resolved row differs from the requested one, and it fails open. A catalog read failure cannot block playback.

Existing rows already stamped failed keep that verdict until a liveness check clears it; this change stops new ones from being created by a source mismatch or an unlisted effective row.

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.
  • Each test this pull request adds meets "Decide what to test" in CONTRIBUTING.md.
  • The Evidence section shows every change a user can see, or says there is none.

AI Disclosure

  • Harness: OpenCode
  • Tool(s): OpenCode coding agent
  • Model(s): Muse Spark
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: n/a

Posted by an AI agent (Muse Spark, OpenCode harness).

A start's effective_media_file_id must name a row the client can show. A
deployed plan answered requested_media_file_id=304999 with
effective_media_file_id=1320729, and 1320729 was not among the item's 452
version rows: progress recorded one row while watch state recorded the other,
so the client could never reconcile what was playing with what was picked.

The detail service now answers the ids of the rows its own version list
carries (the same authorization, fetch and duplicate collapse), and a start
consults that set before planning. A resolver substitution that lands outside
it is refused like any unusable candidate: the candidate that produced it is
excluded and the walk tries the next one. When nothing qualifies the start
answers the retryable version-list terminal instead of planning an unlisted
row, and the refusal never stamps the requested row failed: the release was
not indicted.

Two cases are exempt, both documented at the guard: the requested row itself
(the client's own pick from the list it holds), and a provider-neutral listing
row, which owns no bytes so binding it to the row that owns the served
candidate is ordinary auto selection. An unknown answer (unwired seam, lookup
error, item with no version rows) fails open rather than blocking playback.
A row whose provider served another release's bytes is not a dead release,
but one play attempt left it durable failed:true. The candidate loop joins
each refusal with "no usable stream", and the dead-pin classifier matched that
text, so a single attempt condemned the row. The refusal also never armed the
wrong-source marker, so the versions check could only answer
available:false/failed:true and the user was told "unavailable" instead of
"these bytes are a different release".

The refusal now arms the same process-local served-vs-declared verdict the
version list already renders as source_mismatch, and neither it nor an
unlisted effective row can reach the dead-pin classifier. The start terminal
carries the same vocabulary: the retryable source_mismatch reason, documented
in the playback API contract, with a message naming the version list. The
version list and the player now tell one story about the same bytes.

The dead-end itself is not fatal either way: a refusal that leaves no usable
candidate answers the retryable virtual_source_unavailable terminal naming the
version list, and nothing stamps the requested row failed.

Docs: the catalog and playback API pages record that a playback refusal
publishes source_mismatch, and that an effective row outside the version list
is refused rather than planned.
Two production items showed "Version unavailable" with Play disabled. One
plan had written last_file_id=1320729, a row the item's version list does not
carry, so the page saw a persisted pick it could not select and blocked the
only action. The other had playback_variants[0].default_file_id=416262 marked
failed while 1204391 was not in the list at all.

The page now always resolves a playable row. An explicit pick the viewer made
on this device is kept even when liveness reports it failed, because Play
re-links that row rather than choosing another release behind their back.
Every other preference - the server's last_file_id, or the server's default
row - is skipped when it is failed or unavailable, and the page names the row
it skipped and the row it plays instead. Nothing disables Play while another
row can be tried, and the version list stays one click away.

The shared selection lives in versionRankingUtils so the movie and episode
pages cannot drift. The player also recognizes the new source_mismatch
terminal: it explains the wrong bytes and offers the retry the server marks as
available.
@randrini

Copy link
Copy Markdown
Collaborator Author

Superseded by #459, which contains this change plus the rest of the playback reliability bundle. Closing to keep the review surface to one PR.

@randrini randrini closed this Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants