Define an LR2-aligned policy for negative BPM (#BPMxx via channel 08)

[nulltask]

Context

Found in the BMS spec-compliance audit (finding C-5; also listed as an open TODO in docs/bms-spec.md).

Current behavior

Negative or zero #BPMxx values referenced through channel 08 are dropped by the timing resolver (packages/audio-renderer/src/core/triggers.ts accepts only bpm > 0), so playback continues forward at the previous tempo as if the event did not exist.

Expected behavior

This project's baseline is LR2 behavior: LR2 scrolls backwards on a negative BPM (the chart effectively becomes unplayable past that point), which is the basis of several well-known gimmick charts. beatoraja treats it differently (stop-like), so the policy needs an explicit decision and documentation either way.

Suggested scope

1. Decide the policy (LR2 reverse-scroll reproduction vs. documented non-support).
2. Implement it consistently in the timing resolver and the renderers (TUI / web), or document the deviation in docs/bms-spec.md / docs/player-spec.md.
3. Add regression coverage with a negative-BPM fixture.

Notes

Time-resolution for reverse scroll is non-trivial (event times become non-monotonic), which is why the audit deferred it. Low priority — affects gimmick charts only.

[nulltask]

Investigation: what LR2 actually does with negative BPM

Traced through the OpenLR2 decompilation of LR2body.exe beta3 (@ f5c01e2), cross-checked against hitkey's command memo and the history.txt shipped with LR2 beta3. Short version: the premise that reverse scroll makes event times non-monotonic is wrong for LR2. LR2 never runs time backwards internally — negative BPM is a one-way visual gimmick bolted onto a forward-only timing model, and it is much cheaper to reproduce than the audit assumed.

Mechanics (three stages)

1. Parse — #BPMxx values are read with a plain sign-preserving atof, no validation whatsoever (LR2_bmsload.cpp:2482-2490). Contrast #STOPxx directly below, which requires param2 > 0 (:2495). Channel 03 is two hex nibbles (01–FF), so it structurally cannot carry a negative or zero BPM — channel 08 is the only entry point for negatives.

2. Load-time timing precompute — LR2 precomputes every note's real time at load. In that integration loop, a negative #BPMxx value is converted to its absolute value for the clock math:

double BPM = BPMslot[(int)gp->bmsobj.notes[i].val];
if (BPM < 0.0) { BPM *= -1.0; }          // LR2_bmsload.cpp:2841-2843
nowBPM = BPM * scrollSpeed;
gp->bmsobj.notes[i].val = BPMslot[...];  // :2845 — but the SIGNED value is kept on the note

So every note's realTiming stays monotonically increasing, advancing at |BPM| — the timeline never reverses.

3. Runtime mirror gimmick — when the event pump reaches a BPM event whose stored value is negative (Scene04_Play.cpp:1375-1382), it latches the current position/time, and from then on, permanently:

• Render and judge clocks are mirrored around the latch point (songtimer = latch * 2 - songtimer, :397-400; judge timestamp likewise, :1281-1283). Visually the chart genuinely scrolls in reverse at |BPM| speed, forever — this is the U9 "notes rise back up at the end" effect.
• The event pump freezes (the || bpmChangedBmstime >= 0 gate at :1269): no further BGM keysounds, BGA, or BPM events ever fire.
• Judgment is monotonic-only — per-lane cursors never decrement, so passed notes are never re-judged, and once mirrored time leaves the cursor note's window nothing can be hit or missed again (gauge/combo freeze).
• The song never ends on its own — both natural end-of-song checks (:1552-1558) live inside the frozen pump, so the stage soft-locks in an endless reverse-scrolling state and must be aborted manually (ESC). This issue's "unplayable past that point" is confirmed, and is actually an understatement.

Adjacent findings

• #BPMxx 0: the abs guard is < 0 only, so zero passes through and 240.0 / nowBPM (:2709) puts IEEE infinities into the precomputed table — no crash, positions degenerate. hitkey's test matrix records LR2 as "Stop" for #BPM02 0.
• Undefined slot references: BPMslot[] is sentinel-initialized to -1.0 (:2150), so referencing an undefined #BPMxx behaves exactly like #BPMxx -1 — i.e. it triggers the mirror. hitkey's matrix independently records LR2 applying "-1" to undefined references, which is a nice decompilation-vs-measurement cross-check.
• hitkey's apparent contradiction resolved: LR2 appears both under "reverse" and "ignore: LR2 (partial)" in cmds.htm. Both are right — timing math ignores the sign (absolute value), presentation reverses.
• The changelog matches the design: LR2's beta2 081005 entry files 「Sofa $15 → $1のマイナスbpmに対応しました」 under "accommodations for specific BMS files", and hitkey says "Although LR2 does not support BPM of a negative number fundamentally, famous kusofumen is exceptionally hardcoded. (e.g. Sofa $15 -> $1, U9, etc.)". A one-way end-of-chart gimmick (no judging or BGM needed afterwards) is exactly what Sofa/U9 require.

Implications for this issue

Reproducing LR2 is far cheaper than deferred-for-non-monotonicity suggested:

1. Timing resolver (packages/audio-renderer/src/core/triggers.ts): integrate negative #BPMxx at |BPM| instead of dropping it (note: LR2 advances at |BPM|, not at the previous tempo, so the current drop-and-continue behavior differs from LR2 even before the gimmick) — event times stay monotonic, nothing in the resolver architecture breaks. Emit the first negative-BPM position as a "reversal point" for downstream consumers.
2. Renderers (TUI / web): from the reversal point onward, mirror the display position around the latch — pure presentation.
3. Engine: stop judging and suppress realtime audio triggers past the reversal point.
4. The only genuine design decision left is whether to reproduce "the stage never ends" — practically, ending at the chart's precomputed end time and documenting the deviation (LR2 requires a manual ESC) seems preferable.

Caveat: OpenLR2 is a community decompilation, so individual branches may deviate from the original binary; however the mechanics agree with hitkey's black-box measurements and LR2's own changelog on every point checked.

Sources: GOMazk/OpenLR2 (LR2_bmsload.cpp, Scene04_Play.cpp, structure.h), hitkey — BMS command memo (#BPMXX section and per-player matrices), LR2 beta3 history.txt (beta2 081005 entry), h1dia — BMSを読んでみよう (U9 gimmick anatomy).