@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/voice/corpus-generator.ts

@@ -0,0 +1,413 @@
+/**
+ * Voice Workbench corpus generator (#8785).
+ *
+ * Turns a declarative {@link VoiceScenario} into one labeled audio stream + a
+ * ground-truth JSON the headless runner scores against. Two synthesis paths,
+ * one shape:
+ *
+ *   - Synthetic (default, deterministic, NO native model): formant-resonator
+ *     speech-like PCM (`__test-helpers__/synthetic-speech.ts`) the Silero VAD
+ *     reads as speech. Reproducible in CI with no artifacts — it exercises the
+ *     pipeline plumbing + the scorers/labels, not diarization/WER *accuracy*.
+ *   - Real TTS (gated): an injected {@link CorpusTtsSynthesizer} (Kokoro /
+ *     OmniVoice via the TTS route) produces natural speech. Real diarization
+ *     DER and transcription WER benchmarking need this path.
+ *
+ * `generateVoiceCorpus` is pure (no I/O) so it is unit-testable without disk;
+ * `writeVoiceCorpus` / `readVoiceCorpus` handle the versioned on-disk corpus.
+ * A turn's labels (speaker, transcript, respond decision, entity) come straight
+ * from the scenario, so the ground truth is reproducible regardless of path.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import {
+	AGENT_VOICE_TIMBRE,
+	makeSpeechWithSilenceFixture,
+	type SpeakerTimbre,
+	speakerTimbreForIndex,
+} from "./__test-helpers__/synthetic-speech";
+import {
+	type AugmentationSpec,
+	augmentPcm,
+	specIsClean,
+} from "./corpus-augment";
+import {
+	resolveTurnEnvironment,
+	turnReferenceTranscript,
+	turnSpeakerLabel,
+	type VoiceEnvironment,
+	type VoiceScenario,
+	validateVoiceScenario,
+} from "./voice-scenario";
+import { encodeMonoPcm16Wav } from "./wav-codec";
+
+const DEFAULT_SAMPLE_RATE = 16_000;
+/** Natural speaking rate used to size synthetic speech from text length. */
+const DEFAULT_CHARS_PER_SECOND = 13;
+const DEFAULT_INTER_TURN_SILENCE_SEC = 0.4;
+const MIN_SPEECH_SEC = 0.4;
+/** Cap a single synthetic turn (long-form monologue still lands well under). */
+const MAX_SPEECH_SEC = 45;
+const SYNTHETIC_LEAD_SILENCE_SEC = 0.15;
+const SYNTHETIC_TAIL_SILENCE_SEC = 0.15;
+
+/** Per-turn ground-truth label with sample-accurate timing. */
+export interface CorpusTurnLabel {
+	index: number;
+	/** Diarization ground-truth label (the participant who spoke). */
+	speaker: string;
+	/** Resolved elizaOS entity id for the speaker, when the scenario binds one. */
+	entityId?: string;
+	/** First sample of voiced speech in this turn (after any lead silence). */
+	speechStartSample: number;
+	/** Sample just past the voiced speech (before trailing pauses). */
+	speechEndSample: number;
+	/** First sample of this turn's whole segment in the stream. */
+	segmentStartSample: number;
+	/** Sample just past this turn's whole segment (incl. trailing pauses). */
+	segmentEndSample: number;
+	/** Reference transcript for WER scoring. */
+	referenceTranscript: string;
+	/** Ground truth: should the agent respond to this turn? */
+	expectRespond: boolean;
+	/** Ground truth: is this segment a real end-of-turn boundary? */
+	expectEndOfTurn?: boolean;
+	/** Expected inferred/recognized entity, when the scenario asserts one. */
+	expectedEntity?: string;
+	/** TTS voice id used for this turn (real-TTS path), when set. */
+	ttsVoiceId?: string;
+	/** True when this turn was formant-synthesized rather than real TTS. */
+	synthetic: boolean;
+	/** Acoustic degradation applied to this turn's audio (when any). */
+	environment?: VoiceEnvironment;
+	/** True when this "turn" is the agent's own TTS echoed back (not a user turn). */
+	isAgentEcho?: boolean;
+	/** Ground truth: the speaker is the device owner / primary enrolled voice. */
+	isOwner?: boolean;
+	/** The agent's spoken reply to this turn (drives the echo gate downstream). */
+	agentReplyText?: string;
+}
+
+/**
+ * On-disk corpus ground-truth schema version. Bump when the labeled-corpus
+ * shape changes incompatibly; `readVoiceCorpusGroundTruth` treats a corpus
+ * written by a different version as absent (→ `skipped`, never a stale `pass`).
+ */
+export const CORPUS_SCHEMA_VERSION = 1;
+
+export interface CorpusGroundTruth {
+	/** Labeled-corpus schema version (see {@link CORPUS_SCHEMA_VERSION}). */
+	schemaVersion: number;
+	scenarioId: string;
+	classes: VoiceScenario["classes"];
+	sampleRate: number;
+	totalSamples: number;
+	durationSec: number;
+	participants: Array<{
+		label: string;
+		entityId?: string;
+		isOwner?: boolean;
+		ttsVoiceId?: string;
+	}>;
+	agents?: string[];
+	/** Entity ids the agent answers without a wake word (owner + enrolled). */
+	knownSpeakerEntityIds?: string[];
+	turns: CorpusTurnLabel[];
+	/** True when EVERY turn was synthetic (no real TTS used anywhere). */
+	synthetic: boolean;
+}
+
+export interface GeneratedVoiceCorpus {
+	pcm: Float32Array;
+	sampleRate: number;
+	groundTruth: CorpusGroundTruth;
+}
+
+/**
+ * Real-TTS synthesizer. Gated: when omitted, the generator uses deterministic
+ * synthetic speech. An implementation wraps the TTS route / Kokoro engine and
+ * returns mono PCM at the requested sample rate.
+ */
+export interface CorpusTtsSynthesizer {
+	synthesize(args: {
+		text: string;
+		voiceId?: string;
+		speakerLabel: string;
+		turnIndex: number;
+		isAgentEcho: boolean;
+		sampleRate: number;
+	}): Promise<Float32Array>;
+}
+
+export interface GenerateVoiceCorpusOptions {
+	sampleRate?: number;
+	/** Inject a real-TTS synthesizer to produce natural speech (else synthetic). */
+	synthesizer?: CorpusTtsSynthesizer;
+	/** Silence (s) spliced after a turn that declares no explicit pauses. */
+	interTurnSilenceSec?: number;
+	/** Synthetic-speech sizing: characters of text per second of audio. */
+	charsPerSecond?: number;
+}
+
+/** Deterministic 32-bit FNV-1a of a label → a stable per-speaker synthesis seed. */
+function labelSeed(label: string): number {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < label.length; i++) {
+		h ^= label.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return h >>> 0;
+}
+
+function silenceSamples(ms: number, sampleRate: number): number {
+	return Math.max(0, Math.round((ms / 1000) * sampleRate));
+}
+
+/**
+ * A continuous competing-talker stream for `backgroundTalkersDb`, built from
+ * formant-synth speech (no models) so it is deterministic. `augmentPcm` mixes +
+ * loops it under the real turn at the requested level.
+ */
+function synthesizeBabble(
+	sampleRate: number,
+	lengthSamples: number,
+	seed: number,
+): Float32Array {
+	const fixture = makeSpeechWithSilenceFixture({
+		sampleRate,
+		leadSilenceSec: 0,
+		speechSec: Math.max(0.3, lengthSamples / sampleRate),
+		tailSilenceSec: 0,
+		seed,
+	});
+	return fixture.pcm;
+}
+
+/**
+ * Generate one labeled audio stream for a scenario. Throws on an invalid
+ * scenario (fail loud — a malformed corpus must not silently produce garbage).
+ * A turn that carries only `audioRef` (no `text`) is not synthesizable here and
+ * is rejected; pre-rendered audio is supplied through the corpus on disk.
+ */
+export async function generateVoiceCorpus(
+	scenario: VoiceScenario,
+	options: GenerateVoiceCorpusOptions = {},
+): Promise<GeneratedVoiceCorpus> {
+	const validation = validateVoiceScenario(scenario);
+	if (!validation.valid) {
+		throw new Error(
+			`[voice-corpus] invalid scenario "${scenario.id}": ${validation.errors.join("; ")}`,
+		);
+	}
+
+	const sampleRate = options.sampleRate ?? DEFAULT_SAMPLE_RATE;
+	const charsPerSecond = options.charsPerSecond ?? DEFAULT_CHARS_PER_SECOND;
+	const interTurnSilence = silenceSamples(
+		(options.interTurnSilenceSec ?? DEFAULT_INTER_TURN_SILENCE_SEC) * 1000,
+		sampleRate,
+	);
+	const synthesizer = options.synthesizer;
+
+	const participantByLabel = new Map(
+		scenario.participants.map((p) => [p.label, p]),
+	);
+	// Each participant gets a distinct voice colour, spread evenly across the
+	// timbre range so a blind acoustic diarizer can tell co-present speakers apart
+	// from the audio alone (#9427).
+	const timbreByLabel = new Map<string, SpeakerTimbre>(
+		scenario.participants.map((p, i) => [
+			p.label,
+			speakerTimbreForIndex(i, scenario.participants.length),
+		]),
+	);
+
+	const segments: Float32Array[] = [];
+	const labels: CorpusTurnLabel[] = [];
+	let cursor = 0;
+	let anyReal = false;
+
+	for (let i = 0; i < scenario.turns.length; i++) {
+		const turn = scenario.turns[i];
+		const text = turn.text?.trim();
+		if (!text) {
+			throw new Error(
+				`[voice-corpus] turn[${i}] of "${scenario.id}" has no text to synthesize (audioRef-only turns are supplied via the on-disk corpus, not generated)`,
+			);
+		}
+		const participant = participantByLabel.get(turn.speaker);
+		const ttsVoiceId = turn.ttsVoiceId ?? participant?.ttsVoiceId;
+
+		const segmentStartSample = cursor;
+		let speech: Float32Array;
+		let speechStartOffset: number;
+		let speechEndOffset: number;
+		let synthetic: boolean;
+
+		if (synthesizer) {
+			speech = await synthesizer.synthesize({
+				text,
+				voiceId: ttsVoiceId,
+				speakerLabel: turn.speaker,
+				turnIndex: i,
+				isAgentEcho: turn.isAgentEcho === true,
+				sampleRate,
+			});
+			speechStartOffset = 0;
+			speechEndOffset = speech.length;
+			synthetic = false;
+			anyReal = true;
+		} else {
+			const speechSec = Math.min(
+				MAX_SPEECH_SEC,
+				Math.max(MIN_SPEECH_SEC, text.length / charsPerSecond),
+			);
+			// An agent-echo turn is the agent's OWN TTS bleeding back through the
+			// mic, so it carries the agent's voice — not the labelled speaker's. Real
+			// speaker turns get their distinct per-speaker timbre (#9427).
+			const timbre = turn.isAgentEcho
+				? AGENT_VOICE_TIMBRE
+				: (timbreByLabel.get(turn.speaker) ?? AGENT_VOICE_TIMBRE);
+			const fixture = makeSpeechWithSilenceFixture({
+				sampleRate,
+				leadSilenceSec: SYNTHETIC_LEAD_SILENCE_SEC,
+				speechSec,
+				tailSilenceSec: SYNTHETIC_TAIL_SILENCE_SEC,
+				seed: labelSeed(turn.isAgentEcho ? "__agent__" : turn.speaker),
+				timbre,
+			});
+			speech = fixture.pcm;
+			speechStartOffset = fixture.speechStartSample;
+			speechEndOffset = fixture.speechEndSample;
+			synthetic = true;
+		}
+
+		// Trailing pauses: explicit per-turn gaps, else the default inter-turn gap
+		// (except after the final turn).
+		const pauseTotal =
+			turn.pausesMs && turn.pausesMs.length > 0
+				? turn.pausesMs.reduce((n, ms) => n + silenceSamples(ms, sampleRate), 0)
+				: i < scenario.turns.length - 1
+					? interTurnSilence
+					: 0;
+
+		// Assemble the turn's full segment (voiced speech + trailing pause) so the
+		// per-turn acoustic degradation — reverb ringing into the gap, a noise
+		// floor in the "silence" — covers the pause, not just the speech.
+		let segment: Float32Array = new Float32Array(speech.length + pauseTotal);
+		segment.set(speech, 0);
+
+		const env = resolveTurnEnvironment(scenario, turn);
+		let appliedEnv: VoiceEnvironment | undefined;
+		if (env && !specIsClean(env)) {
+			const seed =
+				env.seed ?? (labelSeed(scenario.id) ^ (i * 0x9e3779b1)) >>> 0;
+			const resolvedEnv: AugmentationSpec = { ...env, seed };
+			const babble =
+				resolvedEnv.backgroundTalkersDb !== undefined
+					? synthesizeBabble(sampleRate, segment.length, (seed ^ 0x1234) >>> 0)
+					: undefined;
+			segment = augmentPcm(segment, sampleRate, resolvedEnv, {
+				...(babble ? { babble } : {}),
+			});
+			appliedEnv = resolvedEnv;
+		}
+
+		segments.push(segment);
+		cursor += segment.length;
+
+		labels.push({
+			index: i,
+			speaker: turnSpeakerLabel(turn),
+			...(participant?.entityId ? { entityId: participant.entityId } : {}),
+			speechStartSample: segmentStartSample + speechStartOffset,
+			speechEndSample: segmentStartSample + speechEndOffset,
+			segmentStartSample,
+			segmentEndSample: cursor,
+			referenceTranscript: turnReferenceTranscript(turn),
+			expectRespond: turn.isAgentEcho ? false : turn.expectRespond,
+			expectEndOfTurn: turn.expectEndOfTurn ?? true,
+			...(turn.expectedEntity ? { expectedEntity: turn.expectedEntity } : {}),
+			...(ttsVoiceId ? { ttsVoiceId } : {}),
+			synthetic,
+			...(appliedEnv ? { environment: appliedEnv } : {}),
+			...(turn.isAgentEcho ? { isAgentEcho: true } : {}),
+			...(participant?.isOwner ? { isOwner: true } : {}),
+			...(turn.agentReplyText ? { agentReplyText: turn.agentReplyText } : {}),
+		});
+	}
+
+	const pcm = new Float32Array(cursor);
+	let offset = 0;
+	for (const segment of segments) {
+		pcm.set(segment, offset);
+		offset += segment.length;
+	}
+
+	const groundTruth: CorpusGroundTruth = {
+		schemaVersion: CORPUS_SCHEMA_VERSION,
+		scenarioId: scenario.id,
+		classes: scenario.classes,
+		sampleRate,
+		totalSamples: pcm.length,
+		durationSec: pcm.length / sampleRate,
+		participants: scenario.participants.map((p) => ({
+			label: p.label,
+			...(p.entityId ? { entityId: p.entityId } : {}),
+			...(p.isOwner ? { isOwner: p.isOwner } : {}),
+			...(p.ttsVoiceId ? { ttsVoiceId: p.ttsVoiceId } : {}),
+		})),
+		...(scenario.agents ? { agents: scenario.agents } : {}),
+		...(scenario.knownSpeakerEntityIds
+			? { knownSpeakerEntityIds: scenario.knownSpeakerEntityIds }
+			: {}),
+		turns: labels,
+		synthetic: !anyReal,
+	};
+
+	return { pcm, sampleRate, groundTruth };
+}
+
+export interface VoiceCorpusPaths {
+	dir: string;
+	audioPath: string;
+	groundTruthPath: string;
+}
+
+/** Persist a generated corpus as `audio.wav` + `ground-truth.json` under `dir`. */
+export function writeVoiceCorpus(
+	corpus: GeneratedVoiceCorpus,
+	dir: string,
+): VoiceCorpusPaths {
+	mkdirSync(dir, { recursive: true });
+	const audioPath = path.join(dir, "audio.wav");
+	const groundTruthPath = path.join(dir, "ground-truth.json");
+	writeFileSync(audioPath, encodeMonoPcm16Wav(corpus.pcm, corpus.sampleRate));
+	writeFileSync(
+		groundTruthPath,
+		`${JSON.stringify(corpus.groundTruth, null, 2)}\n`,
+	);
+	return { dir, audioPath, groundTruthPath };
+}
+
+/**
+ * Read a previously-written corpus's ground truth. Returns null when the corpus
+ * directory or its ground-truth file is absent (the honesty contract — the
+ * runner reports `skipped`, never `pass`, when corpus artifacts are missing).
+ */
+export function readVoiceCorpusGroundTruth(
+	dir: string,
+): CorpusGroundTruth | null {
+	const groundTruthPath = path.join(dir, "ground-truth.json");
+	if (!existsSync(groundTruthPath)) return null;
+	const parsed = JSON.parse(readFileSync(groundTruthPath, "utf8")) as unknown;
+	if (!parsed || typeof parsed !== "object") return null;
+	// Honesty contract: a corpus written by an incompatible schema version is
+	// treated as absent (→ skipped, never a stale pass against drifted labels).
+	if (
+		(parsed as { schemaVersion?: unknown }).schemaVersion !==
+		CORPUS_SCHEMA_VERSION
+	)
+		return null;
+	return parsed as CorpusGroundTruth;
+}

package/src/services/voice/diarization-error-rate.greedy.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import {
+	computeDiarizationErrorRate,
+	type DerResult,
+	type DiarizationSegment,
+} from "./diarization-error-rate";
+
+/**
+ * Greedy-branch coverage for the DER scorer (issue #9147).
+ *
+ * `bestMapping` has two arms: an exact injective permutation search for small
+ * speaker counts, and an O(n²) greedy fallback once `refSpeakers.length +
+ * hypSpeakers.length > maxExactSpeakers` (default 7) — the existing
+ * `diarization-error-rate.test.ts` only ever hits the exact arm. A 7+-speaker
+ * conversation (a noisy multi-party room, the very case `maxDer` exists to
+ * guard) takes the greedy path, so this pins:
+ *   - greedy fires both when forced via a low `maxExactSpeakers` AND on a
+ *     genuine 4-ref/4-hyp (=8 combined) conversation under the default,
+ *   - the greedy mapping stays injective (no ref or hyp reused — the
+ *     usedHyp/usedRef guard), and
+ *   - greedy reproduces the exact arm's DER on separable inputs (where greedy
+ *     is provably optimal), so the fallback is not silently wrong.
+ */
+
+const seg = (
+	speaker: string,
+	startMs: number,
+	endMs: number,
+): DiarizationSegment => ({ speaker, startMs, endMs });
+
+/** A hyp→ref mapping must be injective: every hyp key distinct (free) AND every
+ * ref value distinct (the property the greedy usedRef guard enforces). */
+function expectInjective(mapping: DerResult["mapping"]): void {
+	const hyps = Object.keys(mapping);
+	const refs = Object.values(mapping);
+	expect(new Set(hyps).size).toBe(hyps.length);
+	expect(new Set(refs).size).toBe(refs.length);
+}
+
+describe("computeDiarizationErrorRate — greedy mapping fallback", () => {
+	it("forces the greedy arm via a low maxExactSpeakers and still scores a perfect 2-speaker match", () => {
+		const reference = [seg("alice", 0, 1000), seg("bob", 1000, 2000)];
+		const hypothesis = [seg("spk0", 0, 1000), seg("spk1", 1000, 2000)];
+		// 2 + 2 = 4 combined > maxExact 3 → greedy path (would be exact by default).
+		const result = computeDiarizationErrorRate(reference, hypothesis, {
+			maxExactSpeakers: 3,
+		});
+		expect(result.der).toBe(0);
+		expect(result.confusionMs).toBe(0);
+		expect(result.mapping).toEqual({ spk0: "alice", spk1: "bob" });
+		expectInjective(result.mapping);
+	});
+
+	it("takes the greedy path on a genuine 4-speaker / 8-combined conversation (default maxExact 7)", () => {
+		// 4 ref + 4 hyp = 8 > 7 default → greedy, no options needed.
+		const reference = [
+			seg("a", 0, 1000),
+			seg("b", 1000, 2000),
+			seg("c", 2000, 3000),
+			seg("d", 3000, 4000),
+		];
+		const hypothesis = [
+			seg("w", 0, 1000),
+			seg("x", 1000, 2000),
+			seg("y", 2000, 3000),
+			seg("z", 3000, 4000),
+		];
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.der).toBe(0);
+		expect(result.totalReferenceMs).toBeCloseTo(4000, -1);
+		expect(Object.keys(result.mapping)).toHaveLength(4);
+		expectInjective(result.mapping);
+	});
+
+	it("greedy attributes a swapped span as confusion, not missed/false-alarm, with a tie-break-invariant DER", () => {
+		// 4 ref speakers; the hypothesis reuses label "w" for both a's and d's
+		// span. One of those two spans is necessarily a confusion regardless of
+		// which the greedy tie-break maps w onto — so the DER is deterministic.
+		const reference = [
+			seg("a", 0, 1000),
+			seg("b", 1000, 2000),
+			seg("c", 2000, 3000),
+			seg("d", 3000, 4000),
+		];
+		const hypothesis = [
+			seg("w", 0, 1000),
+			seg("x", 1000, 2000),
+			seg("y", 2000, 3000),
+			seg("w", 3000, 4000),
+		];
+		// 4 ref + 3 hyp = 7 combined; force greedy with maxExact 5.
+		const result = computeDiarizationErrorRate(reference, hypothesis, {
+			maxExactSpeakers: 5,
+		});
+		expect(result.missedMs).toBe(0);
+		expect(result.falseAlarmMs).toBe(0);
+		expect(result.confusionMs).toBeCloseTo(1000, -1); // exactly one swapped span
+		expect(result.der).toBeCloseTo(0.25, 2); // 1000 confusion / 4000 ref
+		expectInjective(result.mapping); // w mapped once, x and y once each
+	});
+
+	it("leaves a zero-overlap hypothesis speaker unmapped (greedy skips s<=0 pairs → false alarm)", () => {
+		const reference = [seg("a", 0, 1000), seg("b", 1000, 2000)];
+		// spk2 talks over a stretch with no reference speaker at all (2000-3000).
+		const hypothesis = [
+			seg("h0", 0, 1000),
+			seg("h1", 1000, 2000),
+			seg("h2", 2000, 3000),
+		];
+		const result = computeDiarizationErrorRate(reference, hypothesis, {
+			maxExactSpeakers: 4,
+		});
+		// h2 never co-occurs with any ref speaker → no mapping entry for it.
+		expect(result.mapping.h2).toBeUndefined();
+		expect(result.falseAlarmMs).toBeCloseTo(1000, -1);
+		expectInjective(result.mapping);
+	});
+
+	it("greedy reproduces the exact arm's DER on a separable 3-speaker case", () => {
+		const reference = [
+			seg("a", 0, 1000),
+			seg("b", 1000, 2000),
+			seg("c", 2000, 3000),
+		];
+		const hypothesis = [
+			seg("p", 0, 1000),
+			seg("q", 1000, 2000),
+			seg("p", 2000, 3000), // c collapsed onto p → a confusion either arm
+		];
+		const exact = computeDiarizationErrorRate(reference, hypothesis, {
+			maxExactSpeakers: 16,
+		});
+		const greedy = computeDiarizationErrorRate(reference, hypothesis, {
+			maxExactSpeakers: 0,
+		});
+		expect(greedy.der).toBeCloseTo(exact.der, 5);
+		expect(greedy.confusionMs).toBeCloseTo(exact.confusionMs, -1);
+		expectInjective(greedy.mapping);
+	});
+});

package/src/services/voice/diarization-error-rate.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import {
+	computeDiarizationErrorRate,
+	type DiarizationSegment,
+	diarizationWithinBudget,
+} from "./diarization-error-rate";
+
+/**
+ * Diarization Error Rate scorer (issue #9147). The voice scenarios carry a
+ * `maxDer` threshold and an `expectedSpeakerLabel` per turn, but nothing
+ * computed DER — so a wrong speaker attribution or a missed overlapping talker
+ * passed silently. This pins the four DER components (missed / false-alarm /
+ * confusion / correct) and the key property that DER is invariant to how the
+ * diarizer NAMES its speakers (it's the partition that matters, not the labels).
+ */
+
+const seg = (
+	speaker: string,
+	startMs: number,
+	endMs: number,
+): DiarizationSegment => ({
+	speaker,
+	startMs,
+	endMs,
+});
+
+describe("computeDiarizationErrorRate", () => {
+	it("is 0 for a perfect match (even with different speaker label names)", () => {
+		const reference = [seg("alice", 0, 1000), seg("bob", 1000, 2000)];
+		// hypothesis splits the timeline identically but calls them spk0/spk1.
+		const hypothesis = [seg("spk0", 0, 1000), seg("spk1", 1000, 2000)];
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.der).toBe(0);
+		expect(result.confusionMs).toBe(0);
+		// optimal mapping pairs the equivalent speakers.
+		expect(result.mapping).toEqual({ spk0: "alice", spk1: "bob" });
+	});
+
+	it("counts missed speech when the system misses a speaker", () => {
+		const reference = [seg("alice", 0, 1000), seg("bob", 1000, 2000)];
+		const hypothesis = [seg("spk0", 0, 1000)]; // bob's 1000ms missed entirely
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.missedMs).toBeCloseTo(1000, -1);
+		expect(result.der).toBeCloseTo(0.5, 1); // 1000 missed / 2000 ref
+	});
+
+	it("counts false alarm when the system hallucinates speech", () => {
+		const reference = [seg("alice", 0, 1000)];
+		const hypothesis = [seg("spk0", 0, 1000), seg("spk1", 1000, 2000)];
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.falseAlarmMs).toBeCloseTo(1000, -1);
+		expect(result.totalReferenceMs).toBeCloseTo(1000, -1);
+	});
+
+	it("counts confusion when the same span is attributed to a swapped speaker", () => {
+		// 3 distinct ref speakers; hypothesis collapses the 3rd onto speaker 1's id,
+		// so the 3rd span is a confusion (wrong speaker), not missed or false alarm.
+		const reference = [
+			seg("a", 0, 1000),
+			seg("b", 1000, 2000),
+			seg("c", 2000, 3000),
+		];
+		const hypothesis = [
+			seg("x", 0, 1000),
+			seg("y", 1000, 2000),
+			seg("x", 2000, 3000),
+		];
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.missedMs).toBe(0);
+		expect(result.falseAlarmMs).toBe(0);
+		expect(result.confusionMs).toBeCloseTo(1000, -1); // c's span mapped to x≠c
+		expect(result.der).toBeCloseTo(1 / 3, 2);
+	});
+
+	it("handles overlapping speech (both speakers active in one span)", () => {
+		// alice 0-2000, bob 1000-2000 → 1000ms of overlap (2 ref speakers).
+		const reference = [seg("alice", 0, 2000), seg("bob", 1000, 2000)];
+		const hypothesis = [seg("spk0", 0, 2000), seg("spk1", 1000, 2000)];
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		// ref speaker-time = 2000 (alice) + 1000 (bob overlap) = 3000ms.
+		expect(result.totalReferenceMs).toBeCloseTo(3000, -1);
+		expect(result.der).toBe(0); // perfectly diarized overlap
+	});
+
+	it("penalizes a missed overlapping talker", () => {
+		const reference = [seg("alice", 0, 2000), seg("bob", 1000, 2000)];
+		const hypothesis = [seg("spk0", 0, 2000)]; // bob's overlapping 1000ms missed
+		const result = computeDiarizationErrorRate(reference, hypothesis);
+		expect(result.missedMs).toBeCloseTo(1000, -1);
+		expect(result.der).toBeCloseTo(1000 / 3000, 2);
+	});
+});
+
+describe("diarizationWithinBudget", () => {
+	it("gates a hypothesis against the scenario maxDer", () => {
+		expect(diarizationWithinBudget({ der: 0.1 }, 0.15)).toBe(true);
+		expect(diarizationWithinBudget({ der: 0.2 }, 0.15)).toBe(false);
+		expect(diarizationWithinBudget({ der: 0 }, 0)).toBe(true);
+	});
+});