Skip to content

fix(playback): keep virtual resolve fallbacks and substitutions honest - #452

Closed
randrini wants to merge 5 commits into
mainfrom
fix/fallback-respects-selection
Closed

randrini wants to merge 5 commits into
mainfrom
fix/fallback-respects-selection

Conversation

@randrini

Copy link
Copy Markdown
Collaborator

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).

  1. A selection with 3 audio and 4 subtitle tracks played a release with 1 audio and 0 subtitles. The plan requested file 613586 and committed 1436768. The version fallback ran because the selected release's resolve timed out, and it took the first sibling that resolved.
  2. substituted_from_file_id and substitution_reason appeared 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, -126 on four consecutive attempts), and each attempt failed at once with context 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-retryable transcode_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_unavailable instead of a fabricated transcode_start_failed. Wait logs report 0 ms left with an explicit bound_exhausted flag instead of a negative wait.

Fallback guard. The fallback reuses the rotation guard #448 added (virtualRotationWouldDropTracks, virtualRuntimePlausible, the duration_contradiction and track_loss reasons) 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 vet on the touched packages — passed.
  • Focused go test -count=1 ./internal/api/handlers ./internal/scanner ./internal/playback — handlers and scanner pass. internal/playback has the two known base failures (TestOnDemandSubtitleSegmentsDoNotWaitForTheStream, TestServeExtractDiscardsACappedDemuxCopy).
  • New and changed tests under -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.sh holds and git diff --check is clean.
  • Fail-before evidence, with the code reverted to main in 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 reported 0, and the cold-path loop attempted all four candidates on the spent deadline (candidate attempts = [a b c d]).
  • The commit and pre-push hooks run make lint-changed on 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: TestHandleStartPlaybackV3DoesNotWaitForSessionSync failed twice on main and 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

  • 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): Muse Spark
  • Model(s): DeepSeek V4.1 Flash 1017
  • Involvement: Fully AI-generated; awaiting human review.
  • Adversarial review: Not performed; this branch is a draft for review.

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

Muse-spark and others added 5 commits November 14, 2026 17:18
…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.
@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