analysis: re-trim tempogram latency to center the grid-phase peak

[vynulldev]

What & why

This started as a bug hunt and ended as a calibration fix. The band-norm EMA in the multiband onset warms up from zero, which inflates the first second of flux frames roughly 100x, and with the amplitude-cubed window weighting the grid phase effectively comes from the track's first strong onsets alone.

Removing that "bug" makes everything worse. Seeding the EMA from the track's real leading level drops <50ms grid agreement with rekordbox by 12 points and grows the half-beat tail, and replacing it with an explicit exponential early-window decay is worse at every time constant. The anchor lives in the inflated first onset frames themselves, not in any preference for early windows, and rekordbox normalizes its own onset novelty with the same kind of one-pole EMA, so its phase is plausibly start-anchored by the very same accident. The warmup stays, and the two refuted experiments stay behind default-off knobs (BandNormWarmupSec, PhaseEarlyTauSec) whose comments warn future readers away from "fixing" it. A new env-gated TestWarmupDiag measures the window-0 dominance directly.

What WAS wrong is the latency constant. TempogramLatencyMs had been centered on the mean phase error, but the error distribution is asymmetric: the well-aligned population sits about 9ms early while a long late tail drags the mean positive. Re-trimming 30 -> 34ms centers the distribution's peak instead of its mean, which takes <10ms grid agreement with rekordbox from 23.9% to 34.3% while <20ms, <50ms and the half-beat tail stay unchanged. The trim was tuned and held-out validated on disjoint slices of a library of imported rekordbox grids, then confirmed with a full run, and the accuracy harness gained env knobs (VYNULL_BEAT_REF_{WARMUP,EARLYTAU}) plus offline latency sweeping from a VYNULL_BEAT_REF_DUMP CSV.

cacheVersion bumps to 29 (28 went to the PWV4 clamp that merged first) so existing libraries re-analyze once and every grid picks up the corrected phase.

Preparing that bump surfaced a long-standing bug it would have triggered: the cache loader discarded (and deleted) any stale-version entry unconditionally, so every cacheVersion bump since v26 has silently wiped user-edited beat grids and re-analyzed those tracks back to the detector's phase. A stale entry carrying GridEdited now stashes its beats/BPM/downbeat and keeps its file until re-analysis lands; the fresh result gets the user's grid re-applied (new waveforms, hand-fixed grid). TestGridEditSurvivesCacheBump pins the behavior, including persistence across a restart.

Hardware testing

No protocol, load-path, or serve-side change, but this DOES change analysis output that decks consume: every beat grid shifts +4ms and the cacheVersion bump re-analyzes existing libraries on upgrade. A hardware smoke (load a track, check the grid/beat indicator looks sane, one re-analyzed track after upgrade) is the honest bar here.

• Tested on: CDJ-2000NXS2 + DJM, live library: v28→v29 upgrade exercised on the real data dir (lazy re-analysis on touch), a user-edited grid survives the bump and serves identically to deck and web UI, beat marks/counter/quantized loops clean, track-end → next-load OK.

Checklist

• go build ./..., go vet ./..., and go test ./... pass
• gofmt -l . is clean
• New source files carry an SPDX header (GPL-3.0-or-later)
• Tested on real hardware (deck + firmware noted above), or this change doesn't affect deck behaviour
• I agree my contribution is licensed under the project's GPLv3