Repository navigation
Conversation
…erequisite #448 (fix/rotation-respects-selection) is open, not merged. This change extends the same guard to the resolve-timeout fallback, so it must reuse virtualRotationWouldDropTracks/virtualRequestedRowIsSelection instead of growing a second policy. Whichever of the two lands first, the other's call sites keep working.
A virtual resolve attempt took its bound from a nested WithTimeout on a deadline an earlier stage had already spent. The derived context expired before the wait began, the resolver logged a negative bound (bound_ms=-34/-65/-95/-126 on four consecutive attempts), and every attempt failed immediately with context deadline exceeded. Callers read that as a provider listing failure: the failover loop ran on a spent budget, the version fallback used it to justify a release substitution, and the transport reported the last attempt as a non-retryable transcode_start_failed. Derive each attempt's budget from the request's remaining time under an explicit cap (virtualResolveAttemptBudget), refuse an attempt when nothing is left, and stop the cold-path candidate loop once its single deadline is spent. Logs report 0 ms left with an explicit bound_exhausted flag instead of a negative wait. A transport startup with no budget left answers the retryable provider_unavailable instead of a fabricated transcode verdict. The cold-path and stale-pin tests now pin the new truth: a spent budget is refused, and the recovery listing is identified by its own sub-budget rather than by a global call ordinal.
The cold-start version fallback walked alternate releases on any provider listing failure, including a resolve timeout, and served the first that resolved. Production: a 3-audio/4-subtitle selection played as a 1-audio/0-subtitle sibling. Apply the rotation guard #448 introduced to the fallback: a substitute that contradicts the item's runtime (duration_contradiction) or offers fewer audio or subtitle tracks than the selected row (track_loss) is refused, and when every substitute would lose the selection the start answers a retryable terminal that names the version list instead of serving a poorer menu. A walk whose own budget is spent does not run at all: a timeout is not evidence that the selected release cannot serve, and every alternate would be resolved on the same expired deadline.
The plan's substituted_from_file_id and substitution_reason were set in the domain type, but the v2 projection rebuilt the plan field by field and dropped both. Across 35 production plan/replan decisions with 14 effective-id changes the client saw them zero times, so it could only guess which release it got. Project both fields into the v2 plan and publish them on every replan that commits a row other than the requested one, not only the explicit version-pick hunt. The cause comes from a reason the plan already carries, a decode rotation, or the replan's failure class. Additive: two optional plan fields, regenerated OpenAPI and web types, and a short playback API section naming the substitution vocabulary. Tests pin the serialized body, the omitted-when-unsubstituted case, and a replan rotation.
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
A virtual start could play a different release than the one the viewer selected, and the plan did not say so. Both were measured on a deployed integration build (Chrome, 2026-11-14).
613586and committed1436768. The version fallback ran because the selected release's resolve timed out, and it took the first sibling that resolved.substituted_from_file_idandsubstitution_reasonappeared zero times across 35 plan/replan decisions with 14 effective-id changes. A client can only guess, and it guessed wrong.The timeout itself was misdiagnosed. The resolve inherited a deadline an earlier stage had already spent: the derived context expired before the wait began, the resolver logged a negative bound (
bound_ms=-34,-65,-95,-126on four consecutive attempts), and each attempt failed at once withcontext deadline exceeded. The start read that as a provider listing failure, walked alternates on an exhausted budget, and the transport reported the last attempt as a non-retryabletranscode_start_failed.This affects anyone starting or replanning a virtual-library title whose selected release is dead, slow, or rotated mid-session.
Related issue: N/A
Validation tasks: none identified; the affected surfaces are virtual start/replan version substitution and virtual resolve budgets, for a validator to confirm.
Approach
Resolve budget. One helper derives each virtual resolve attempt's bound from the request's remaining time under an explicit cap, and refuses the attempt when nothing is left. It is used by the cold-path candidate loop, the fallback walk's per-candidate budget, and transport startup. A transport startup with no time left now answers the retryable
provider_unavailableinstead of a fabricatedtranscode_start_failed. Wait logs report 0 ms left with an explicitbound_exhaustedflag instead of a negative wait.Fallback guard. The fallback reuses the rotation guard #448 added (
virtualRotationWouldDropTracks,virtualRuntimePlausible, theduration_contradictionandtrack_lossreasons) instead of a second policy. A substitute that contradicts the item's runtime or offers fewer audio or subtitle tracks than the selected row is refused. When every substitute would lose the selection, the start returns a retryable terminal naming the version list. A fallback whose own budget is spent does not run at all: a timeout does not prove the selected release cannot serve.Wire reporting. The v2 projection rebuilt the plan field by field and dropped both substitution fields. They are now projected and published on every replan that commits a row other than the requested one, not only the explicit version-pick hunt. The cause comes from a reason the plan already carries, a decode rotation, or the replan's failure class. The change is additive: two optional plan fields, regenerated OpenAPI and web types, and a short playback API section naming the vocabulary.
Stack note. #448 (
fix/rotation-respects-selection) is open, not merged, and this change reuses its guard. The branch merges #448 so the guard has one implementation, so this PR also shows #448's commit. If #448 lands first, this diff collapses to the three commits after that merge.Validation
go build ./...— passed.go veton the touched packages — passed.go test -count=1 ./internal/api/handlers ./internal/scanner ./internal/playback— handlers and scanner pass.internal/playbackhas the two known base failures (TestOnDemandSubtitleSegmentsDoNotWaitForTheStream,TestServeExtractDiscardsACappedDemuxCopy).-race— passed.make verify-playback-fixtures— matrix unchanged.make verify-apiv2-openapi,make verify-apiv2-web-types,make verify-apiv2-fixtures— current.make lint-changed BASE_REF=kipsilabs/main— 0 issues.scripts/check-fork-invariants.shholds andgit diff --checkis clean.mainin a separate worktree: the timeout served the track-losing substitute (served substitute 2 (1 audio/0 subtitles) for a 3/4 selection), the v2 body omitted both fields, a replan rotation reported0, and the cold-path loop attempted all four candidates on the spent deadline (candidate attempts = [a b c d]).make lint-changedon the host, where cgo code cannot typecheck without libvips. The same gate was run in the Go build container and is clean; both pushes used--no-verify.One failure outside the task's known-failure list:
TestHandleStartPlaybackV3DoesNotWaitForSessionSyncfailed twice onmainand with this change under heavy load, then passed on a quieter run. It is a 1 s timing assertion and unrelated to this diff.Risks
Two additive optional plan fields; older clients ignore them. No migration, no auth or authority change. A fallback that used to succeed on a track-poor sibling now ends in a retryable terminal that names the version list; that is the intended trade, and it only affects selections that would have lost tracks.
Checklist
AI Disclosure
Posted by an AI agent (Muse Spark, OpenCode harness).