= 0 ? "+" : ""}${fixed} dB`;
}
+/**
+ * Phase 1 v2 emits `truePeak: null` for digital silence (no defined dBTP).
+ * Report the measured peak, or an em-dash when it's absent — matching the
+ * house convention (`formatNumber` renders missing values as "—").
+ */
+export function formatTruePeak(truePeak: number | null, suffix = " dBTP"): string {
+ return truePeak === null ? "—" : `${truePeak.toFixed(1)}${suffix}`;
+}
+
+/**
+ * Master-limiter ceiling target derived from the true peak. When the peak is
+ * null (silence) there is nothing to duck below, so fall back to the -0.3 dB
+ * safety cap — the same value the formula yields for any peak ≥ -0.2 dBTP —
+ * keeping the recommendation card actionable rather than showing a blank.
+ */
+export function masterCeilingDb(truePeak: number | null): number {
+ return truePeak === null ? -0.3 : Math.min(-0.3, truePeak - 0.1);
+}
+
function midiToNoteName(midi: number): string {
const noteNames = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"] as const;
const clamped = Math.max(0, Math.min(127, Math.round(midi)));
@@ -531,7 +550,7 @@ function getSonicMeasurements(
const sets: Record
= {
kick: [
{ icon: "🎚", label: "Low Bass", value: formatSignedDb(phase1.spectralBalance.lowBass) },
- { icon: "📏", label: "Peak", value: `${phase1.truePeak.toFixed(1)} dB` },
+ { icon: "📏", label: "Peak", value: formatTruePeak(phase1.truePeak) },
{ icon: "⏱", label: "Tempo", value: `${Math.round(phase1.bpm)} BPM` },
],
bass: [
@@ -587,7 +606,7 @@ function getSonicMeasurements(
widthAndStereo: [
{ icon: "↔", label: "Width", value: phase1.stereoWidth.toFixed(2) },
{ icon: "📡", label: "Correlation", value: phase1.stereoCorrelation.toFixed(2) },
- { icon: "🧲", label: "Peak", value: `${phase1.truePeak.toFixed(1)} dB` },
+ { icon: "🧲", label: "Peak", value: formatTruePeak(phase1.truePeak) },
],
harmonicContent: [
{ icon: "🎼", label: "Key", value: phase1.key ?? "Unknown" },
@@ -815,7 +834,7 @@ function buildDerivedChainParameters(
case "DRUM PROCESSING":
return [
{ label: "Tempo Sync", value: `${Math.round(phase1.bpm)} BPM` },
- { label: "Punch Target", value: `${phase1.truePeak.toFixed(1)} dB peak` },
+ { label: "Punch Target", value: formatTruePeak(phase1.truePeak, " dBTP peak") },
];
case "BASS PROCESSING":
return [
@@ -846,7 +865,7 @@ function buildDerivedChainParameters(
);
case "MASTER BUS":
return [
- { label: "Ceiling", value: `${Math.min(-0.3, phase1.truePeak - 0.1).toFixed(1)} dB` },
+ { label: "Ceiling", value: `${masterCeilingDb(phase1.truePeak).toFixed(1)} dB` },
{ label: "Integrated Loudness", value: `${phase1.lufsIntegrated.toFixed(1)} LUFS` },
];
default:
@@ -897,7 +916,7 @@ function makeLimiterFallbackCard(phase1: Phase1Result, nextOrder: number) {
trackContext: "Master",
workflowStage: prettifyWorkflowStage("MASTER"),
parameters: [
- { label: "Ceiling", value: `${Math.min(-0.3, phase1.truePeak - 0.1).toFixed(1)} dB` },
+ { label: "Ceiling", value: `${masterCeilingDb(phase1.truePeak).toFixed(1)} dB` },
{ label: "Integrated Loudness", value: `${phase1.lufsIntegrated.toFixed(1)} LUFS` },
{ label: "Stereo Width", value: phase1.stereoWidth.toFixed(2) },
],
@@ -1132,7 +1151,7 @@ function buildStereoWidthPatchCard(
{ label: "Stereo Width", value: phase1.stereoWidth.toFixed(2) },
{ label: "Correlation Floor", value: phase1.stereoCorrelation.toFixed(2) },
{ label: "Bass mono below", value: "100 Hz" },
- { label: "Ceiling", value: `${Math.min(-0.3, phase1.truePeak - 0.1).toFixed(1)} dB` },
+ { label: "Ceiling", value: `${masterCeilingDb(phase1.truePeak).toFixed(1)} dB` },
],
proTip:
"Make width moves in the highs first, then mono-check kick and bass before committing the setting.",
diff --git a/apps/ui/src/services/backendPhase1Client.ts b/apps/ui/src/services/backendPhase1Client.ts
index 05f7082d..3ba9c12d 100644
--- a/apps/ui/src/services/backendPhase1Client.ts
+++ b/apps/ui/src/services/backendPhase1Client.ts
@@ -556,9 +556,12 @@ export function parsePhase1Result(value: unknown): Phase1Result {
}
const lufsIntegrated = expectNumber(phase1, "lufsIntegrated");
- const truePeak = expectNumber(phase1, "truePeak");
+ // Phase 1 v2: truePeak is `null` for digital silence (no defined dBTP). Accept
+ // an explicit null, but still reject a malformed/missing field via expectNumber.
+ const truePeak = phase1.truePeak === null ? null : expectNumber(phase1, "truePeak");
const explicitPlr = toNumber(phase1.plr);
- const normalizedPlr = explicitPlr ?? roundToTwoDecimals(truePeak - lufsIntegrated);
+ const normalizedPlr =
+ explicitPlr ?? (truePeak !== null ? roundToTwoDecimals(truePeak - lufsIntegrated) : null);
const monoCompatible = phase1.monoCompatible === true
? true
: phase1.monoCompatible === false
diff --git a/apps/ui/src/services/loudnessGuardrails.ts b/apps/ui/src/services/loudnessGuardrails.ts
index ba487b52..8b605f2d 100644
--- a/apps/ui/src/services/loudnessGuardrails.ts
+++ b/apps/ui/src/services/loudnessGuardrails.ts
@@ -3,11 +3,10 @@ import type { Phase1Result } from '../types';
/**
* Objective, genre-independent loudness defects.
*
- * Unit note: Phase 1 `truePeak` is a LINEAR amplitude proxy (see
- * apps/backend/JSON_SCHEMA.md — "linear amplitude proxy (rounded)"; the
- * full-scale audio fixture in apps/backend/tests/test_audio_fixture.py asserts
- * truePeak ≈ 1.0), NOT dBTP. 1.0 == 0 dBFS full scale; > 1.0 == inter-sample
- * over. Always compare in linear amplitude, never in dB.
+ * Unit note: as of Phase 1 schema v2, `truePeak` is dBTP (see
+ * apps/backend/JSON_SCHEMA.md). 0.0 dBTP == full scale; > 0.0 dBTP ==
+ * inter-sample over. Compare in dBTP. (In v1 this field was a linear amplitude
+ * proxy with a 1.0 boundary; the v2 migration moved it to dBTP.)
*
* The robust trigger is `saturationDetail.clippedSampleCount` (stereo samples
* with |x| >= 0.9999) — unit-independent and unambiguous. truePeak is a
@@ -18,8 +17,8 @@ import type { Phase1Result } from '../types';
* safety net only asserts correctness — that a measured defect is addressed.
*/
-/** Linear amplitude above which `truePeak` is an inter-sample over (0 dBFS). */
-export const TRUE_PEAK_OVER_LINEAR = 1.0;
+/** dBTP above which `truePeak` is an inter-sample over (0.0 dBTP == full scale). */
+export const TRUE_PEAK_OVER_DBTP = 0.0;
export type LoudnessDefectKind = 'CLIPPING' | 'TRUE_PEAK_OVER';
@@ -60,7 +59,7 @@ export function loudnessDefectsDemandingAction(phase1: Phase1Result): LoudnessDe
if (
typeof truePeak === 'number' &&
Number.isFinite(truePeak) &&
- truePeak > TRUE_PEAK_OVER_LINEAR
+ truePeak > TRUE_PEAK_OVER_DBTP
) {
defects.push({
kind: 'TRUE_PEAK_OVER',
diff --git a/apps/ui/src/services/phase1Picker.ts b/apps/ui/src/services/phase1Picker.ts
index 95c72448..bfa8aba3 100644
--- a/apps/ui/src/services/phase1Picker.ts
+++ b/apps/ui/src/services/phase1Picker.ts
@@ -46,7 +46,7 @@ export function pickPhase1Value(
* formatCitedValue("reverbDetail.rt60", 2.04) → "2.04s"
* formatCitedValue("bpmConfidence", 0.86) → "86%"
* formatCitedValue("lufsIntegrated", -9.3) → "-9.3 LUFS"
- * formatCitedValue("truePeak", -0.2) → "-0.2 dB"
+ * formatCitedValue("truePeak", -0.2) → "-0.2 dBTP"
* formatCitedValue("key", "F minor") → "F minor"
* formatCitedValue("acidDetail.isAcid", true) → "yes"
* formatCitedValue("anything", null | undefined) → ""
@@ -100,13 +100,17 @@ export function formatCitedValue(path: string, value: unknown): string {
return `${value.toFixed(2)}s`;
}
- // True peak / dynamic / peak family — dB without sign-prefix rule.
- // Match by suffix so nested paths like `kickDetail.crestFactor` also pick
- // up the dB formatter rather than falling through to the bare-number rule.
+ // True peak is dBTP (Phase 1 v2).
+ if (path === 'truePeak' && typeof value === 'number') {
+ return `${value.toFixed(1)} dBTP`;
+ }
+
+ // Dynamic / peak family — dB without sign-prefix rule. Match by suffix so
+ // nested paths like `kickDetail.crestFactor` also pick up the dB formatter
+ // rather than falling through to the bare-number rule.
if (
typeof value === 'number' &&
- (path === 'truePeak' ||
- /(^|\.)(crestFactor|dynamicSpread|plr)$/.test(path))
+ /(^|\.)(crestFactor|dynamicSpread|plr)$/.test(path)
) {
return `${value.toFixed(1)} dB`;
}
diff --git a/apps/ui/src/services/phase2Validator.ts b/apps/ui/src/services/phase2Validator.ts
index 5b98f471..82a9bd47 100644
--- a/apps/ui/src/services/phase2Validator.ts
+++ b/apps/ui/src/services/phase2Validator.ts
@@ -58,11 +58,10 @@ const TRIVIAL_CITATION_DOMINANCE_THRESHOLD = 0.6;
/**
* Confidence below which paired recommendation text must use hedged language.
- * Most detector confidences are normalized 0-1. `bpmConfidence` is Essentia's
- * unbounded RhythmExtractor2013 confidence, so it uses its own threshold.
+ * All detector confidences — including `bpmConfidence`, normalized to 0-1 as of
+ * Phase 1 schema v2 — share this threshold.
*/
const NORMALIZED_LOW_CONFIDENCE_THRESHOLD = 0.4;
-const BPM_LOW_CONFIDENCE_THRESHOLD = 1.0;
/**
* Phase 1 fields whose presence-but-zero-citations should warn. The list now
@@ -1231,10 +1230,7 @@ function lowConfidenceTriggerForCitation(
const value = readNumberAtPath(phase1, confidencePath);
if (value === null) return null;
- const threshold =
- confidencePath === 'bpmConfidence'
- ? BPM_LOW_CONFIDENCE_THRESHOLD
- : NORMALIZED_LOW_CONFIDENCE_THRESHOLD;
+ const threshold = NORMALIZED_LOW_CONFIDENCE_THRESHOLD;
if (value >= threshold) return null;
return {
field: cited,
diff --git a/apps/ui/src/types/measurement.ts b/apps/ui/src/types/measurement.ts
index 426f309e..87cf5ecd 100644
--- a/apps/ui/src/types/measurement.ts
+++ b/apps/ui/src/types/measurement.ts
@@ -628,7 +628,10 @@ export interface GenreDetail {
}
export interface Phase1Result {
+ /** Phase 1 schema version, e.g. "phase1.v2". Absent on pre-v2 snapshots. */
+ phase1Version?: string | null;
bpm: number;
+ /** Tempo confidence, normalized 0-1 (Phase 1 v2; raw Essentia ~0-5.32 in v1). */
bpmConfidence: number;
bpmPercival?: number | null;
bpmAgreement?: boolean | null;
@@ -649,7 +652,8 @@ export interface Phase1Result {
lufsRange?: number | null;
lufsMomentaryMax?: number | null;
lufsShortTermMax?: number | null;
- truePeak: number;
+ /** Max true peak in dBTP (Phase 1 v2; was a linear amplitude proxy in v1). 0.0 == full scale, > 0 == inter-sample over. `null` for digital silence (no defined dBTP). */
+ truePeak: number | null;
plr?: number | null;
crestFactor?: number | null;
dynamicSpread?: number | null;
diff --git a/apps/ui/src/utils/exportUtils.ts b/apps/ui/src/utils/exportUtils.ts
index 1d0f4fdf..2b42de7e 100644
--- a/apps/ui/src/utils/exportUtils.ts
+++ b/apps/ui/src/utils/exportUtils.ts
@@ -54,7 +54,7 @@ export function generateMarkdown(
md += `- **Time Signature**: ${phase1.timeSignature}\n`;
md += `- **Duration (s)**: ${phase1.durationSeconds}\n`;
md += `- **Integrated LUFS**: ${phase1.lufsIntegrated}\n`;
- md += `- **True Peak**: ${phase1.truePeak}\n`;
+ md += `- **True Peak**: ${phase1.truePeak === null ? '—' : `${phase1.truePeak} dBTP`}\n`;
md += `- **Stereo Width**: ${phase1.stereoWidth}\n`;
md += `- **Stereo Correlation**: ${phase1.stereoCorrelation}\n\n`;
diff --git a/apps/ui/tests/services/analysisResultsViewModel.test.ts b/apps/ui/tests/services/analysisResultsViewModel.test.ts
index 53da2cc2..aa1b9b0c 100644
--- a/apps/ui/tests/services/analysisResultsViewModel.test.ts
+++ b/apps/ui/tests/services/analysisResultsViewModel.test.ts
@@ -5,6 +5,8 @@ import {
buildPatchCards,
buildPatchGroups,
buildSonicElementCards,
+ formatTruePeak,
+ masterCeilingDb,
toConfidenceBadges,
truncateAtSentenceBoundary,
truncateBySentenceCount,
@@ -787,4 +789,38 @@ describe('analysisResultsViewModel helpers', () => {
const confidenceRow = guide?.parameters.find((p) => p.label === 'Melody Confidence');
expect(confidenceRow?.value).toBe('72% (Workable draft)');
});
+
+ it('renders true peak as an em-dash when the v2 measurement is null (silence)', () => {
+ // Phase 1 v2 emits truePeak: null for digital silence (no defined dBTP).
+ // Building the card must not crash on an unguarded .toFixed and the Peak
+ // readout should fall back to the house "—" convention.
+ const silent = { ...measurement, truePeak: null };
+ const sonicCards = buildSonicElementCards(silent, {
+ kick: 'Kick sentence.',
+ bass: 'Bass sentence.',
+ melodicArp: 'Arp sentence.',
+ grooveAndTiming: 'Groove sentence.',
+ effectsAndTexture: 'Fx sentence.',
+ widthAndStereo: 'Width sentence.',
+ harmonicContent: 'Harmony sentence.',
+ });
+ const kickCard = sonicCards.find((card) => card.id === 'kick');
+ const peakRow = kickCard?.measurements.find((m) => m.label === 'Peak');
+ expect(peakRow?.value).toBe('—');
+ });
+
+ it('formatTruePeak renders dBTP for a number and an em-dash for null', () => {
+ expect(formatTruePeak(-0.2)).toBe('-0.2 dBTP');
+ expect(formatTruePeak(0)).toBe('0.0 dBTP');
+ expect(formatTruePeak(-1.3, ' dBTP peak')).toBe('-1.3 dBTP peak');
+ expect(formatTruePeak(null)).toBe('—');
+ });
+
+ it('masterCeilingDb ducks below the peak but falls back to the -0.3 dB cap for null', () => {
+ // A hot peak yields peak - 0.1; any peak ≥ -0.2 is capped at -0.3; silence
+ // (null) has no peak to duck below, so the same -0.3 safety cap applies.
+ expect(masterCeilingDb(-3.0)).toBeCloseTo(-3.1, 5);
+ expect(masterCeilingDb(0)).toBeCloseTo(-0.3, 5);
+ expect(masterCeilingDb(null)).toBeCloseTo(-0.3, 5);
+ });
});
diff --git a/apps/ui/tests/services/loudnessGuardrails.test.ts b/apps/ui/tests/services/loudnessGuardrails.test.ts
index 49eb0616..15f72d87 100644
--- a/apps/ui/tests/services/loudnessGuardrails.test.ts
+++ b/apps/ui/tests/services/loudnessGuardrails.test.ts
@@ -1,27 +1,28 @@
import { describe, it, expect } from 'vitest';
import {
- TRUE_PEAK_OVER_LINEAR,
+ TRUE_PEAK_OVER_DBTP,
citationAddressesLoudnessDefect,
loudnessDefectsDemandingAction,
} from '../../src/services/loudnessGuardrails';
import type { Phase1Result } from '../../src/types';
// Minimal Phase1Result — only the fields the predicate reads matter; the rest
-// are irrelevant to loudness defect detection.
+// are irrelevant to loudness defect detection. Default truePeak is a normal
+// mastered peak below full scale (negative dBTP).
const phase1 = (overrides: Partial): Phase1Result =>
- ({ truePeak: 0.5, ...overrides }) as Phase1Result;
+ ({ truePeak: -1.0, ...overrides }) as Phase1Result;
describe('loudnessDefectsDemandingAction', () => {
it('returns no defects for a clean master (no clipping, peak below full scale)', () => {
const result = loudnessDefectsDemandingAction(
- phase1({ truePeak: 0.5, saturationDetail: { clippedSampleCount: 0 } as any }),
+ phase1({ truePeak: -1.0, saturationDetail: { clippedSampleCount: 0 } as any }),
);
expect(result).toEqual([]);
});
it('flags CLIPPING when clippedSampleCount > 0', () => {
const result = loudnessDefectsDemandingAction(
- phase1({ truePeak: 0.5, saturationDetail: { clippedSampleCount: 1280 } as any }),
+ phase1({ truePeak: -1.0, saturationDetail: { clippedSampleCount: 1280 } as any }),
);
expect(result).toHaveLength(1);
expect(result[0]).toMatchObject({
@@ -31,14 +32,14 @@ describe('loudnessDefectsDemandingAction', () => {
});
});
- it('flags TRUE_PEAK_OVER when truePeak exceeds full scale (linear > 1.0)', () => {
+ it('flags TRUE_PEAK_OVER when truePeak exceeds full scale (dBTP > 0)', () => {
const result = loudnessDefectsDemandingAction(phase1({ truePeak: 1.1 }));
expect(result).toHaveLength(1);
expect(result[0]).toMatchObject({ kind: 'TRUE_PEAK_OVER', field: 'truePeak', value: 1.1 });
});
- it('does not flag a true peak exactly at full scale (1.0 is the boundary, not an over)', () => {
- const result = loudnessDefectsDemandingAction(phase1({ truePeak: TRUE_PEAK_OVER_LINEAR }));
+ it('does not flag a true peak exactly at full scale (0.0 dBTP is the boundary, not an over)', () => {
+ const result = loudnessDefectsDemandingAction(phase1({ truePeak: TRUE_PEAK_OVER_DBTP }));
expect(result).toEqual([]);
});
@@ -49,8 +50,9 @@ describe('loudnessDefectsDemandingAction', () => {
expect(result.map(d => d.kind).sort()).toEqual(['CLIPPING', 'TRUE_PEAK_OVER']);
});
- it('treats truePeak as LINEAR, so a dB-style negative value never trips the over check', () => {
- // Guards the unit contract: truePeak is a linear amplitude proxy, not dBTP.
+ it('treats truePeak as dBTP, so a normal master below full scale (negative dBTP) is not an over', () => {
+ // Guards the unit contract: truePeak is dBTP (Phase 1 v2). -0.2 dBTP is below
+ // full scale, so it is not an inter-sample over.
const result = loudnessDefectsDemandingAction(phase1({ truePeak: -0.2 }));
expect(result).toEqual([]);
});
@@ -59,7 +61,7 @@ describe('loudnessDefectsDemandingAction', () => {
expect(loudnessDefectsDemandingAction(phase1({ truePeak: null as any }))).toEqual([]);
expect(
loudnessDefectsDemandingAction(
- phase1({ truePeak: 0.5, saturationDetail: null as any }),
+ phase1({ truePeak: -1.0, saturationDetail: null as any }),
),
).toEqual([]);
expect(loudnessDefectsDemandingAction(phase1({ truePeak: NaN }))).toEqual([]);
diff --git a/apps/ui/tests/services/phase1Picker.test.ts b/apps/ui/tests/services/phase1Picker.test.ts
index b485cd22..36818fb7 100644
--- a/apps/ui/tests/services/phase1Picker.test.ts
+++ b/apps/ui/tests/services/phase1Picker.test.ts
@@ -115,7 +115,7 @@ describe('formatCitedValue', () => {
});
it('formats dB-family paths', () => {
- expect(formatCitedValue('truePeak', -0.2)).toBe('-0.2 dB');
+ expect(formatCitedValue('truePeak', -0.2)).toBe('-0.2 dBTP');
expect(formatCitedValue('crestFactor', 11.6)).toBe('11.6 dB');
});
diff --git a/apps/ui/tests/services/phase2Validator.test.ts b/apps/ui/tests/services/phase2Validator.test.ts
index 0e5a01e7..f2692bbb 100644
--- a/apps/ui/tests/services/phase2Validator.test.ts
+++ b/apps/ui/tests/services/phase2Validator.test.ts
@@ -1089,8 +1089,10 @@ describe('validatePhase2Consistency', () => {
expect(violations).toHaveLength(0);
});
- it('uses bpmConfidence < 1.0 as the low-confidence tempo threshold', () => {
- const phase1 = createBasePhase1({ bpm: 126, bpmConfidence: 0.82 });
+ it('uses the normalized 0.4 threshold for low-confidence bpmConfidence (v2)', () => {
+ // Phase 1 v2: bpmConfidence is normalized 0-1, so it shares the standard
+ // 0.4 hedge threshold (0.2 < 0.4 → unhedged tempo claim is a violation).
+ const phase1 = createBasePhase1({ bpm: 126, bpmConfidence: 0.2 });
const phase2 = createBasePhase2({
abletonRecommendations: [
{
@@ -1109,11 +1111,11 @@ describe('validatePhase2Consistency', () => {
v => v.type === 'LOW_CONFIDENCE_NOT_HEDGED',
);
expect(violations).toHaveLength(1);
- expect(violations[0].message).toContain('bpmConfidence < 1');
+ expect(violations[0].message).toContain('bpmConfidence < 0.4');
});
- it('does not apply the normalized 0.4 threshold to reliable bpmConfidence values', () => {
- const phase1 = createBasePhase1({ bpm: 126, bpmConfidence: 1.2 });
+ it('does not flag a reliable (>= 0.4) bpmConfidence value', () => {
+ const phase1 = createBasePhase1({ bpm: 126, bpmConfidence: 0.9 });
const phase2 = createBasePhase2({
abletonRecommendations: [
{
@@ -1375,7 +1377,8 @@ describe('Loudness action presence (objective safety net)', () => {
const clippingPhase1 = () =>
createBasePhase1({
- truePeak: 0.9,
+ // -0.5 dBTP: below full scale, so CLIPPING is the only defect under test.
+ truePeak: -0.5,
saturationDetail: { clippedSampleCount: 1280, clippedSamplePercent: 0.4 } as any,
});
@@ -1415,7 +1418,7 @@ describe('Loudness action presence (objective safety net)', () => {
expect(loudnessViolations(validatePhase2Consistency(phase1, phase2))).toHaveLength(0);
});
- it('warns on an unaddressed true-peak over (linear > 1.0)', () => {
+ it('warns on an unaddressed true-peak over (dBTP > 0)', () => {
const result = validatePhase2Consistency(createBasePhase1({ truePeak: 1.1 }), newShapePhase2());
const loudness = loudnessViolations(result);
expect(loudness).toHaveLength(1);
@@ -1424,7 +1427,8 @@ describe('Loudness action presence (objective safety net)', () => {
it('does not warn for a clean master (no clipping, peak below full scale)', () => {
const phase1 = createBasePhase1({
- truePeak: 0.8,
+ // -0.8 dBTP: a clean master sitting below full scale.
+ truePeak: -0.8,
saturationDetail: { clippedSampleCount: 0, clippedSamplePercent: 0 } as any,
});
expect(loudnessViolations(validatePhase2Consistency(phase1, newShapePhase2()))).toHaveLength(0);
diff --git a/docs/adr/0002-phase1-loudness-units-v2.md b/docs/adr/0002-phase1-loudness-units-v2.md
new file mode 100644
index 00000000..0dfb5ef7
--- /dev/null
+++ b/docs/adr/0002-phase1-loudness-units-v2.md
@@ -0,0 +1,75 @@
+# ADR 0002 — Phase 1 loudness-field units (schema v2)
+
+**Status:** Accepted
+**Date:** 2026-06-01
+**Supersedes:** Partially supersedes [ADR 0001](0001-phase1-json-schema-v1.md) for two fields.
+**Anchor:** [PURPOSE.md](../../PURPOSE.md) quality invariants #1 (measurement authority) and #4 (honest uncertainty).
+
+## Context
+
+ADR 0001 declared the Phase 1 payload "v1" and classified unit changes and range
+changes as breaking (forbidden under v1). Two v1 fields carried representations that
+fought the grain of nearly every consumer:
+
+1. **`truePeak`** was emitted as a **linear amplitude proxy** (1.0 == 0 dBFS). The
+ conventional meaning of "true peak" is **dBTP**, and a code audit found ~12 consumers
+ already *assumed* dBTP — several were latent bugs because the field was actually linear:
+ - `analysisResultsViewModel.ts` computed master ceilings as `min(-0.3, truePeak - 0.1)`,
+ which always returned `-0.3` for a linear `truePeak ≈ 1.0`.
+ - `MeasurementDashboard.tsx` rendered `{ value: truePeak, suffix: 'dBTP' }` (showing
+ `1.00 dBTP` instead of `0.0`) and scaled the meter on a dB range.
+ - `analyze_core.analyze_plr` computed `truePeak_linear - lufsIntegrated` — a linear
+ amplitude minus a dB value, an incoherent number.
+ Only `loudnessGuardrails.ts` correctly treated the field as linear.
+
+2. **`bpmConfidence`** was the raw Essentia `RhythmExtractor2013` confidence (~0–5.32),
+ the *only* `*Confidence` field not normalized to 0–1. Consumers that assumed 0–1
+ mis-rendered it (`exportUtils.ts` multiplied by 100 → up to ~500%; the confidence-band
+ ladder mis-banded it), and the validator carried a special-case threshold.
+
+The WASM loudness package (`packages/loudness-spectro-wasm`) also emits `true_peak_dbtp`.
+Keeping v1's linear/raw representations required converting at ~20 fragile consumer sites;
+fixing the *source* makes the majority of consumers correct by default.
+
+## Decision
+
+Bump the Phase 1 measurement schema to **`phase1.v2`** and change two field units:
+
+| Field | v1 | v2 |
+|---|---|---|
+| `truePeak` | linear amplitude proxy (1.0 == full scale) | **dBTP** (0.0 == full scale, > 0 == inter-sample over); `null` for silence |
+| `bpmConfidence` | raw Essentia confidence (~0–5.32) | **normalized 0–1** (raw / 5.0, clamped) |
+
+A new top-level string field **`phase1Version`** (e.g. `"phase1.v2"`) is added so consumers
+can detect the generation — this is the canonical mechanism ADR 0001 anticipated for a v2 bump.
+
+Derived/consumer effects:
+- `plr` is now a direct dB-domain subtraction (`truePeak_dBTP - lufsIntegrated`); its *unit*
+ (LU) is unchanged, so this is a correctness fix, not a contract change.
+- `loudnessGuardrails.ts` over-detection moves from `truePeak > 1.0` (linear) to
+ `truePeak > 0.0` (dBTP).
+- `bpmConfidence` now shares the standard `0.4` low-confidence hedge threshold; the
+ validator's BPM-specific threshold is removed.
+
+## Compatibility
+
+This is a **breaking change** under ADR 0001's policy (units + range). It is acceptable
+because ASA is, in practice, its own only consumer (personal use), and the change makes the
+payload *more* conventional, not less. External consumers can branch on `phase1Version`.
+ADR 0001's compatibility table still governs all other fields.
+
+## Enforcement / where v2 is pinned
+
+- `EXPECTED_TOP_LEVEL_KEYS` and `FAST_MODE_POPULATED_FIELDS` in `tests/test_analyze.py`
+ (now include `phase1Version`).
+- The Phase 1 golden snapshot (`tests/fixtures/golden/phase1_default.json`), re-baselined
+ for `truePeak: 0.0` (dBTP) and `plr: 5.6`.
+- Dedicated unit tests in `tests/test_loudness_r128.py` (dBTP `analyze_true_peak`, dB-domain
+ `analyze_plr`) and the fixture expectations in `tests/test_audio_fixture.py`.
+- `Phase1Result` typing in `apps/ui/src/types/measurement.ts` and `JSON_SCHEMA.md`.
+
+## Not in scope
+
+- No other field units change. No machine-readable JSON Schema artifact (still deferred).
+- The WASM package is not yet wired in; this ADR only aligns the Essentia path's *units*
+ with dBTP convention (which happens to match WASM), easing a future parity comparison.