fix(loudness): Phase 1 v2 — truePeak→dBTP, bpmConfidence→0–1, coherent PLR

[slittycode]

Summary

This is PR-A of a staged program (see session). It is the Phase 1 schema v2 migration for the loudness fields — WS1 of the "what's next" plan, which a consumer audit grew from a small fix into a deliberate units migration.

Why: mapping every consumer of truePeak showed the codebase already overwhelmingly assumed dBTP, while the field actually emitted a linear amplitude proxy:

• analysisResultsViewModel.ts computed master ceilings as min(-0.3, truePeak - 0.1) → always -0.3 for a linear truePeak ≈ 1.0.
• MeasurementDashboard.tsx rendered { value: truePeak, suffix: 'dBTP' } → showed 1.00 dBTP instead of 0.0.
• analyze_core.analyze_plr computed truePeak_linear - lufsIntegrated — a linear amplitude minus a dB value (incoherent).
• Only loudnessGuardrails.ts correctly treated it as linear.

Plus bpmConfidence was the only *Confidence field not in 0–1 (raw Essentia ~0–5.32), which exportUtils.ts rendered as up to ~500%.

Rather than convert at ~20 fragile consumer sites, we fix the source. This makes the majority of consumers correct by default and matches the convention the WASM loudness package also uses.

Changes

• truePeak → dBTP (0.0 == full scale, > 0 == inter-sample over; null for silence).
• bpmConfidence → normalized 0–1 (raw / 5.0, clamped).
• plr is now a coherent dB-domain subtraction (truePeak_dBTP − lufsIntegrated) in analyze_core, the server_phase1 HTTP fallback, and the phase1_evaluation consistency gate. Unit (LU) unchanged — a correctness fix.
• New top-level phase1Version = "phase1.v2" so consumers can detect the generation (ADR 0001's prescribed v2 mechanism).
• loudnessGuardrails over-check moves to dBTP (> 0); phase2Validator drops its special-case bpmConfidence threshold (now shares the standard 0.4 hedge threshold).
• loudness_rec_evaluation (research-only) converts the now-dBTP peak back to linear for its limiter-ceiling reachability math.
• Re-baselined the Phase 1 golden (truePeak: 0.0, plr: 5.6); added dedicated analyze_plr (dB subtraction) and dBTP analyze_true_peak unit tests; updated fixture expectations, Phase1Result typing, and JSON_SCHEMA.md.
• ADR 0002 records the v2 bump, superseding ADR 0001 for these two fields only.

Test plan

• apps/backend: ./venv/bin/python -m unittest discover -s tests — green.
• Golden re-baselined deliberately (UPDATE_PHASE1_GOLDEN=1); diff is exactly phase1Version added + plr 6.6→5.6 + truePeak 1.0→0.0.
• apps/ui: npm run lint (tsc) clean, npm run test:unit 716/716, npm run build clean.
• Smoke (npm run test:smoke) runs in CI (needs the live stack).

Notes

This is a breaking Phase 1 contract change under ADR 0001's policy (units + range), taken deliberately and recorded in ADR 0002 — acceptable here because ASA is effectively its own only consumer, and the change makes the payload more conventional. All other fields are unchanged.

https://claude.ai/code/session_01Wq1vE1D7o3W9xZKSHXz43Q

---

Generated by Claude Code

[slittycode]

Verdict: COMMENT

Summary

A deliberate, well-scoped Phase 1 schema migration: truePeak moves from a linear amplitude proxy to dBTP, bpmConfidence normalizes to 0–1, and plr becomes a coherent dB-domain subtraction. The math is correct throughout, the ADR documents the breaking change properly, and the new TestAnalyzePlrIsDbtpMinusLufs / TestAnalyzeTruePeakEmitsDbtp test classes are genuinely meaningful (not coverage padding). CI was still in progress at review time; smoke tests are gated there.

Findings

Should fix

analysisResultsViewModel.ts — three display sites still label truePeak with "dB" instead of "dBTP" (lines 534, 590, 818: `${phase1.truePeak.toFixed(1)} dB` and `${phase1.truePeak.toFixed(1)} dB peak`). The values are now correct (the v2 migration fixed the semantics), but the unit suffix is wrong and will confuse anyone comparing the display to a true-peak meter. Lines 849/900/1135 (the derived Math.min(-0.3, truePeak - 0.1) ceiling) are fine — the formula is now semantically meaningful for the first time and the "dB" suffix on a ceiling number is close enough. MeasurementDashboard.tsx:1670 already has suffix: 'dBTP' correct.

Worth considering

Phase1Result.truePeak is typed number (non-nullable) in measurement.ts, but the backend can now emit null for silent signals and already could emit null on TruePeakDetector failure. analysisResultsViewModel.ts calls phase1.truePeak.toFixed(1) without a null guard in multiple places; TypeScript won't catch this because the type says it's always a number. This is pre-existing, but the v2 change makes the null path more reachable (any silent signal, not just a crashed detector). Worth typing it as number | null and guarding the display callsites.

On the bpmConfidence threshold shift

The validator's effective low-confidence threshold moves from raw 1.0 → raw 2.0 (i.e., normalized 0.2 → 0.4). This is correct: the JSON_SCHEMA.md v1 docs always said "above 2.0 is reliable" while the validator was inconsistently testing against 1.0. The v2 migration aligns code to its own documentation. Not a concern — just noting it's more than a unit change.

Test results

CI still running at review time (Backend, Frontend, Loudness WASM in-progress; Chromatic passed). Can't report final counts. The smoke gate (npm run test:smoke) is deferred to CI per the PR checklist.

New unit tests verified by inspection:

• analyze_plr(-8.9, 0.0)["plr"] == 8.9 ✓
• analyze_plr(-9.0, -1.2)["plr"] == 7.8 ✓
• 20*log10(1.032) ≈ 0.27 → rounds to 0.3 dBTP ✓
• 20*log10(0.8913) ≈ -1.0 dBTP ✓
• Golden delta (truePeak 1.0 → 0.0, plr 6.6 → 5.6) consistent with lufsIntegrated ≈ -5.6 ✓
• Audio fixture delta (plr 9.9 → 8.9) consistent with lufsIntegrated ≈ -8.9 ✓

Phase boundary check

Clean. No Phase 2/3 code overrides Phase 1 measurements. PLR derivation in analyze_core / server_phase1 reads measured fields and produces a derived value — not an override, same as before. loudness_rec_evaluation.py's linear reconversion is research-only and correctly isolated.

---

Generated by Claude Code