fix(forwarder): qoe_downshift_overshoot false-positive on startup ramp (no actual downshift)

[jonathaneoliver]

Summary

qoe_downshift_overshoot fires during the startup ramp even when the player never downshifts — it climbs from the conservative startup rung (360p) straight up to the top. The label is meant for rampdown / pyramid-descent over-correction (#669), not the initial ascent, so this is a false positive.

Evidence

Observed on the Android TV / HLS / live_offset=6 startup sweep finding (exp seed-config-androidtv-hls-live-offset-startup + its rep batch rep-8c0d9e-*).

Play b104c934-dae9-4790-85fa-cee6e6424afa label histogram:

critical=*qoe_cirr_breach
info=*qoe_tier_premium
warning=stall_segment
info=shift_up                  <- the only rendition-direction event
warning=*qoe_cirr_concerning
warning=*qoe_downshift_overshoot   <- fired anyway
info=first_frame

There is no shift_down in the whole play. The rendition path is purely upward: first frame at 640x360 (~1 Mbps, the floor rung) → shift_up → 3840x2160 (qoe_tier_premium). So nothing downshifted, yet qoe_downshift_overshoot is present. The single labelled row lands at the startup boundary (before a steady rendition is established).

Root cause

downshiftOvershootLabel in analytics/go-forwarder/qoe_labels.go:439 is purely instantaneous — it fires whenever the selected rung sits DownshiftOvershootRungs (=2) or more rungs below the rung the effective cap supports:

if ceilingIdx-curIdx >= cfg.ABR.DownshiftOvershootRungs {
    return qoeLabel(SevWarning, "qoe_downshift_overshoot")
}

It has no notion of direction or history. At startup the player legitimately sits at the floor rung (curIdx≈0) while it ramps up; with a high cap-supported ceiling the ceilingIdx - curIdx >= 2 gap trips immediately — indistinguishable from a genuine over-downshift. The doc comment even says the intent is "the overshoot we want flagged on rampdown / pyramid-descent runs," i.e. descent, not ascent.

Proposed fix

Gate the label on an actual downshift / directionality, so the conservative startup ascent can't trip it. Options (any that satisfies the acceptance test):

• Only fire if the player has previously held a higher rung earlier in this play (a real decrease), or after a recent shift_down; suppress while still in the initial upshift ramp from the startup rung.
• Equivalently: don't fire until the play has first reached (at least once) the cap-supported ceiling / steady state.

Keep the existing rampdown / pyramid-descent behaviour intact.

Acceptance

• A startup ramp 360p → top with no shift_down must NOT emit qoe_downshift_overshoot.
• Genuine rampdown / pyramid-descent over-correction still fires (existing labels_test.go overshoot cases keep passing).
• Add a regression case in analytics/go-forwarder/labels_test.go covering the startup-ascent-no-downshift scenario.

Found via the #772 automated sweep (config class).

[jonathaneoliver]

Points: 3 (Fibonacci)
Effort: ~3–4 hours
Priority: P2 — next sprint; this pollutes sweep findings (#772) with spurious warning chips but has no user-facing playback impact and no blocking dependency
Value: medium — directly fixes measurement correctness for the QoE classifier (wrong labels undermine automated sweep conclusions), but affects only the analysis layer, not playback or the user experience itself

Rationale:

Surface area is tightly bounded: one function (downshiftOvershootLabel in qoe_labels.go, line 439), one call site (line 163), and one test file (labels_test.go). The fix is a directionality guard — fire only after the play has previously held a rung above the current selection (i.e. a real downshift has occurred). The cleanest implementation adds a peakRungIdx (or reuses downshiftTimes as a presence check — non-empty means at least one shift_down was recorded) to playLabelState, then threads ps into downshiftOvershootLabel(cfg, ps, r) to consult it. That is a signature change touching the one call site and the existing TestQoEDownshiftOvershoot helper, but both are self-contained. The non-regression risk on genuine rampdown/pyramid-descent cases is low provided the guard only adds a precondition (len(ps.downshiftTimes) > 0 is sufficient — startup ramps never emit shift_down, so the slice stays empty until a real downshift occurs). Add one new labels_test.go case: startup ascent (cap 8 Mbps, ladder 1/5/8, no prior shift_down in state) must not fire.

No split needed at 3 points.

[jonathaneoliver]

Refinement — define overshoot temporally, and don't overlap with the under-utilization labels

Two design points that sharpen the fix beyond "add a startup guard":

1. qoe_downshift_overshoot should be a transient pattern, not an instantaneous gap.
The textbook meaning of overshoot is an over-correction that is reversed: the player downshifted ≥X rungs in reaction to a dip, then recovered (upshifted) shortly after. So the detector should be temporal — a shift_down of ≥DownshiftOvershootRungs followed by an upshift back within a short window W. The current downshiftOvershootLabel (qoe_labels.go:439) has no time and no direction (just "selected rung ≥2 below the cap-supported ceiling at this instant"), which is exactly why the startup ascent trips it. The forwarder already tracks recent downshift timestamps for qoe_downshift_storm, so the same per-play state can gate overshoot — no new plumbing.

2. "Playing below what the bandwidth supports" is a different signal that already has labels.
The instantaneous "selected rung below the ceiling" condition this label currently checks is really steady under-utilization, which is already covered — and more correctly (throughput-based, not cap-based):

• qoe_abr_conservative — uses < underutilized-ratio of measured throughput AND a fitting higher rung exists (should have climbed).
• qoe_ladder_gap — headroom exists but no rung fits (player correct).
• qoe_min_variant_stuck — parked at the bottom rung.

So today's downshift_overshoot double-counts under-utilization as "overshoot." Redefining it as the transient down-then-up pattern removes that overlap and drops the startup false-positive as a side effect.

Revised acceptance:

• Startup ascent 360p→top with no shift_down ⇒ no qoe_downshift_overshoot (still required).
• A sustained low selection that never recovers ⇒ NOT overshoot (it's qoe_abr_conservative / qoe_min_variant_stuck's job); overshoot must see a downshift then a recovery upshift within W.
• Genuine rampdown / pyramid-descent over-correction (drop-then-climb-back) still fires.
• Add W (recovery window) + reuse the existing downshift-time state; regression cases in labels_test.go for: startup-ascent (no fire), down-and-stays-down (no fire), down-then-quick-up (fire).

This likely nudges scope from "guard one call site" toward a small temporal rule, but the downshift-time tracking already exists, so still ~points:3.