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

package/src/services/voice/checkpoint-policy.ts

@@ -0,0 +1,336 @@
+/**
+ * Voice checkpoint policy — thin VAD-event → checkpoint-op translator that
+ * sits between the voice loop (turn-controller / pipeline / vad) and the
+ * `GatedCheckpointManager` (`../checkpoint-manager.ts`).
+ *
+ * Why a separate policy module?
+ *
+ *   - The constraint envelope on this scaffold explicitly forbids editing
+ *     `turn-controller.ts`, `pipeline.ts`, `pipeline-impls.ts`, `vad.ts`,
+ *     `scheduler.ts`, `phrase-chunker.ts`, `barge-in.ts`, `transcriber.ts`,
+ *     and anything under `voice/kokoro/` / `voice/streaming-asr/`. Those
+ *     files are owned by other agents.
+ *   - But the upstream merge for `--ctx-checkpoints` lands "any week now,"
+ *     and the JS-side rollback policy is what the merge unlocks. So the
+ *     policy lives here as a free-standing module that the turn controller
+ *     can pick up in a follow-up PR by injecting it into its VAD handler
+ *     and calling `onSpeechPause` / `onSpeechResume` / `onSpeechEndCommit`
+ *     / `onHardStop` at the matching transitions.
+ *   - The wiring required in `turn-controller.ts` is documented in the
+ *     `WIRING-INSTRUCTIONS` comment at the bottom of this file and in
+ *     `docs/eliza-1-ctx-checkpoints-integration.md`. We intentionally do
+ *     NOT apply the wiring here — that is a follow-up PR scoped to the
+ *     turn-controller owner.
+ *
+ * Policy summary (one C1 per turn, named `pre-speculative-T<turnId>`):
+ *
+ *   - `onSpeechPause(turnId)` — VAD reports the user stopped speaking but
+ *     hangover hasn't elapsed. Save C1 and let the caller kick the
+ *     speculative drafter. If the save fails the policy logs and continues
+ *     (callers MUST treat speculative work as best-effort).
+ *
+ *   - `onSpeechResume(turnId)` — VAD fires `speech-active` within the
+ *     rollback window. If we previously kicked a speculative draft (the
+ *     caller flips `speculativeFired=true` to tell us), restore C1 so the
+ *     KV state is rolled back to the pre-draft point. Otherwise no-op.
+ *
+ *   - `onSpeechEndCommit(turnId)` — VAD's hangover elapsed; the pause was a
+ *     real turn boundary. The speculative draft is promoted. Erase C1: we
+ *     no longer need a rollback target for this turn.
+ *
+ *   - `onHardStop(turnId)` — caller-initiated cancellation (e.g. user
+ *     pressed mute, app backgrounded). If C1 exists, prefer restoring to
+ *     it so the KV cache is in a known-clean state for the next turn; if
+ *     C1 isn't around, fall back to `cancel` (the gated manager will
+ *     either issue `DELETE /slots/<id>` or invoke the SSE-disconnect
+ *     callback depending on the gate).
+ *
+ * All four hooks are idempotent and survive a missing C1 by no-op'ing.
+ * Errors from the underlying manager are caught and reported through the
+ * `events.onError` sink — the policy NEVER throws back into the voice
+ * loop, because a failing checkpoint endpoint must not be able to break
+ * audio.
+ *
+ * The policy holds no state of its own beyond the per-turn name; the
+ * `GatedCheckpointManager` owns the registry, the REST client, and the
+ * capability cache.
+ *
+ * --- WIRING-INSTRUCTIONS (turn-controller.ts) -----------------------------
+ *
+ * The turn-controller owner adds (after the upstream merge lands):
+ *
+ *   1. Construct a `GatedCheckpointManager` once at session start and
+ *      pass it into a `CheckpointPolicy` instance (one per slot).
+ *   2. In the VAD `speech-pause` handler, immediately after the pause
+ *      hangover timer is armed:
+ *
+ *          await policy.onSpeechPause(this.turnId, this.slotId);
+ *          // ...kick speculative drafter against the partial transcript
+ *
+ *   3. In the VAD `speech-active` handler (only when arriving within the
+ *      rollback window — the controller already tracks this):
+ *
+ *          await policy.onSpeechResume(this.turnId, this.slotId, {
+ *            speculativeFired: this.speculativeFired,
+ *          });
+ *          // ...abort the speculative drafter
+ *
+ *   4. In the `speech-end` → SPEAKING transition (after the verifier
+ *      promotes the draft):
+ *
+ *          await policy.onSpeechEndCommit(this.turnId, this.slotId);
+ *
+ *   5. In the `dispose()` path and any other hard-stop site (mute, app
+ *      background, error shutdown, barge-in mid-SPEAKING):
+ *
+ *          await policy.onHardStop(this.turnId, this.slotId, () => {
+ *            this.speculativeAbort?.abort();  // SSE-disconnect callback
+ *          });
+ *
+ *   6. Feature flag: pass `useCtxCheckpoints` through to the
+ *      `GatedCheckpointManager` constructor; when off the policy still
+ *      runs but every call is a logged no-op.
+ *
+ * The turn-controller must NOT call `mgr.save/restore/erase/cancel`
+ * directly — those names are reserved for the policy so the gated/no-op
+ * branching stays in one place. The `policy.events.onError` sink lets the
+ * controller forward checkpoint failures into its existing voice-loop
+ * telemetry without coupling to the REST error type.
+ */
+
+import { logger } from "@elizaos/core";
+import type {
+	CheckpointHandle,
+	GatedCheckpointManager,
+	SseDisconnectFn,
+} from "../checkpoint-manager";
+
+/**
+ * Errors are surfaced through this sink rather than rethrown. The voice
+ * loop wires it into its existing telemetry; tests assert on it directly.
+ */
+export interface CheckpointPolicyEvents {
+	onError?(
+		op: "save" | "restore" | "erase" | "cancel",
+		error: unknown,
+		turnId: string,
+	): void;
+	/**
+	 * Called after a successful save so callers can record the handle in
+	 * their per-turn state if they want to bypass the name-based lookup on
+	 * the matching restore.
+	 */
+	onSaved?(turnId: string, handle: CheckpointHandle): void;
+	/** Called after a successful restore. */
+	onRestored?(turnId: string, handle: CheckpointHandle): void;
+	/** Called when the policy decides to no-op (registry miss, gate off). */
+	onNoop?(
+		op: "save" | "restore" | "erase" | "cancel",
+		turnId: string,
+		reason: "gate-off" | "registry-miss" | "no-speculative",
+	): void;
+}
+
+export interface CheckpointPolicyOptions {
+	/** Gated manager. Owned by the caller; one per session. */
+	manager: GatedCheckpointManager;
+	/** Events sink (errors + observability). Optional. */
+	events?: CheckpointPolicyEvents;
+}
+
+/** Optional second arg to `onSpeechResume` so the policy knows whether
+ * a speculative draft actually fired. When `false`, the resume is a no-op
+ * (no draft means nothing to roll back).
+ */
+export interface SpeechResumeContext {
+	speculativeFired: boolean;
+}
+
+/**
+ * Voice checkpoint policy. Stateless w.r.t. checkpoints (the manager owns
+ * the registry) — only holds the manager + event sink. One instance per
+ * voice session is enough; the `turnId` argument scopes each operation.
+ */
+export class CheckpointPolicy {
+	private readonly manager: GatedCheckpointManager;
+	private readonly events: CheckpointPolicyEvents;
+
+	constructor(opts: CheckpointPolicyOptions) {
+		this.manager = opts.manager;
+		this.events = opts.events ?? {};
+	}
+
+	/**
+	 * VAD `speech-pause`. Save C1. Caller kicks the speculative drafter on
+	 * its own — the policy doesn't care; it just guarantees the rollback
+	 * target exists.
+	 */
+	async onSpeechPause(turnId: string, slotId: number): Promise<void> {
+		const name = checkpointNameFor(turnId);
+		if (!this.manager.isFeatureFlagOn()) {
+			this.events.onNoop?.("save", turnId, "gate-off");
+			logger.debug(
+				`[checkpoint-policy] onSpeechPause(${turnId}) — gate off, skipping save`,
+			);
+			return;
+		}
+		try {
+			const handle = await this.manager.save(slotId, name);
+			if (handle === null) {
+				// Gate flipped on but capability check declined — manager logs.
+				this.events.onNoop?.("save", turnId, "gate-off");
+				return;
+			}
+			this.events.onSaved?.(turnId, handle);
+		} catch (error) {
+			this.events.onError?.("save", error, turnId);
+			logger.warn(
+				{ error, turnId, slotId },
+				"[checkpoint-policy] save failed; speculative draft will run without rollback target",
+			);
+		}
+	}
+
+	/**
+	 * VAD `speech-active` within the rollback window. Restore C1 ONLY if
+	 * the caller actually kicked a speculative draft — otherwise the KV
+	 * state hasn't been mutated and we'd be doing a needless REST round
+	 * trip.
+	 */
+	async onSpeechResume(
+		turnId: string,
+		slotId: number,
+		ctx: SpeechResumeContext,
+	): Promise<void> {
+		if (!ctx.speculativeFired) {
+			this.events.onNoop?.("restore", turnId, "no-speculative");
+			logger.debug(
+				`[checkpoint-policy] onSpeechResume(${turnId}) — no speculative draft fired; skipping restore`,
+			);
+			return;
+		}
+		const name = checkpointNameFor(turnId);
+		if (!this.manager.isFeatureFlagOn()) {
+			this.events.onNoop?.("restore", turnId, "gate-off");
+			logger.debug(
+				`[checkpoint-policy] onSpeechResume(${turnId}) — gate off, skipping restore`,
+			);
+			return;
+		}
+		try {
+			const ok = await this.manager.restore(slotId, name);
+			if (!ok) {
+				this.events.onNoop?.("restore", turnId, "registry-miss");
+				logger.warn(
+					{ turnId, slotId, name },
+					"[checkpoint-policy] restore returned false (handle not found / expired); KV cache may be dirty until next pause",
+				);
+				return;
+			}
+			const handle = this.manager.getNamedHandle(name);
+			if (handle) this.events.onRestored?.(turnId, handle);
+		} catch (error) {
+			this.events.onError?.("restore", error, turnId);
+			logger.warn(
+				{ error, turnId, slotId },
+				"[checkpoint-policy] restore failed; KV cache may contain speculative writes",
+			);
+		}
+	}
+
+	/**
+	 * VAD's hangover elapsed → real turn boundary. Speculative draft is
+	 * being promoted, so C1 is no longer needed. Erase frees the registry
+	 * slot (the server-side LRU handles its own eviction independently).
+	 */
+	async onSpeechEndCommit(turnId: string, slotId: number): Promise<void> {
+		const name = checkpointNameFor(turnId);
+		if (!this.manager.isFeatureFlagOn()) {
+			this.events.onNoop?.("erase", turnId, "gate-off");
+			logger.debug(
+				`[checkpoint-policy] onSpeechEndCommit(${turnId}) — gate off, skipping erase`,
+			);
+			return;
+		}
+		try {
+			await this.manager.erase(slotId, name);
+		} catch (error) {
+			this.events.onError?.("erase", error, turnId);
+			logger.warn(
+				{ error, turnId, slotId },
+				"[checkpoint-policy] erase failed; registry entry remains until TTL eviction",
+			);
+		}
+	}
+
+	/**
+	 * Hard-stop: caller-initiated cancellation. Prefer rolling back to C1
+	 * (clean KV state for the next turn) when available, else cancel any
+	 * in-flight decode on the slot. `sseDisconnect` is the existing voice-
+	 * loop abort hook — required because the gated manager falls back to
+	 * it when the REST endpoints aren't available.
+	 */
+	async onHardStop(
+		turnId: string,
+		slotId: number,
+		sseDisconnect: SseDisconnectFn,
+	): Promise<void> {
+		const name = checkpointNameFor(turnId);
+		if (!this.manager.isFeatureFlagOn()) {
+			sseDisconnect(slotId);
+			this.events.onNoop?.("cancel", turnId, "gate-off");
+			return;
+		}
+		const existing = this.manager.getNamedHandle(name);
+		if (existing) {
+			try {
+				const ok = await this.manager.restore(slotId, name);
+				if (ok) {
+					this.events.onRestored?.(turnId, existing);
+				}
+				// Also erase: the registry slot serves no further purpose after
+				// a hard stop, and leaving it pinned through TTL eviction is
+				// wasteful.
+				try {
+					await this.manager.erase(slotId, name);
+				} catch (eraseError) {
+					this.events.onError?.("erase", eraseError, turnId);
+				}
+				return;
+			} catch (error) {
+				this.events.onError?.("restore", error, turnId);
+				logger.warn(
+					{ error, turnId, slotId },
+					"[checkpoint-policy] hard-stop restore failed; falling back to cancel",
+				);
+			}
+		}
+		try {
+			await this.manager.cancel(slotId, sseDisconnect);
+		} catch (error) {
+			this.events.onError?.("cancel", error, turnId);
+			logger.warn(
+				{ error, turnId, slotId },
+				"[checkpoint-policy] cancel failed; voice loop SSE-disconnect already invoked",
+			);
+		}
+	}
+}
+
+/**
+ * Per-turn checkpoint name. Keeps the namespace stable so a hard-stop
+ * after a normal commit doesn't collide with the next turn's C1.
+ *
+ * The format is the only thing callers outside the policy ever see —
+ * `GatedCheckpointManager.getNamedHandle('pre-speculative-T123')` returns
+ * the same handle the policy used. Keep it stable; if the format changes
+ * in a later change, audit every consumer of `getNamedHandle`.
+ */
+export function checkpointNameFor(turnId: string): string {
+	// The gated manager's REST filename validation allows
+	// `[A-Za-z0-9._-]`, and turn ids in the voice loop are short integer
+	// strings. Sanitize defensively for the unlikely case where turn
+	// ids carry colons or slashes.
+	const safe = turnId.replace(/[^A-Za-z0-9._-]/g, "_");
+	return `pre-speculative-T${safe}`;
+}

package/src/services/voice/composite-eot-classifier.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from "vitest";
+import { CompositeEotClassifier } from "./eot-classifier";
+import type { FfiEotScorer } from "./fused-eot-scorer";
+
+/** A stub fused scorer that returns a fixed model probability. */
+function mockScorer(probability: number) {
+	const score = vi.fn(async () => ({
+		probability,
+		latencyMs: 3,
+		promptTokens: 5,
+	}));
+	const scorer = { modelLabel: "mock-eot", score } as unknown as FfiEotScorer;
+	return { scorer, score };
+}
+
+describe("CompositeEotClassifier", () => {
+	it("trusts the heuristic and skips the model when it is confident — sentence-final punctuation", async () => {
+		const { scorer, score } = mockScorer(0.0);
+		const c = new CompositeEotClassifier({ model: scorer });
+		// "Hello there." → punctuation → heuristic 0.95 (confidence 0.9 ≥ cutoff).
+		expect(await c.score("Hello there.")).toBeCloseTo(0.95, 5);
+		expect(score).not.toHaveBeenCalled();
+	});
+
+	it("trusts the heuristic and skips the model when it is confident — trailing conjunction", async () => {
+		const { scorer, score } = mockScorer(0.99);
+		const c = new CompositeEotClassifier({ model: scorer });
+		// "I want to go and" → trailing conjunction → heuristic 0.15 (confidence 0.7).
+		expect(await c.score("I want to go and")).toBeCloseTo(0.15, 5);
+		expect(score).not.toHaveBeenCalled();
+	});
+
+	it("defers to the model in the ambiguous middle (no syntactic signal)", async () => {
+		const { scorer, score } = mockScorer(0.82);
+		const c = new CompositeEotClassifier({ model: scorer });
+		// 5 words, no punctuation, last word a pronoun → heuristic 0.5 (confidence
+		// 0) → the blend is the pure model probability.
+		expect(await c.score("tell me more about it")).toBeCloseTo(0.82, 5);
+		expect(score).toHaveBeenCalledTimes(1);
+	});
+
+	it("blends model + heuristic for a mid-confidence heuristic (short utterance)", async () => {
+		const { scorer, score } = mockScorer(0.2);
+		const c = new CompositeEotClassifier({ model: scorer });
+		// "okay sure" → 2 words → heuristic 0.7 (confidence 0.4 < cutoff) → model
+		// runs; blend = 0.2·(1−0.4) + 0.7·0.4 = 0.40.
+		expect(await c.score("okay sure")).toBeCloseTo(0.4, 5);
+		expect(score).toHaveBeenCalledTimes(1);
+	});
+
+	it("signal() reports the model source only when the model contributed", async () => {
+		const { scorer } = mockScorer(0.6);
+		const c = new CompositeEotClassifier({ model: scorer });
+		expect((await c.signal("Done.")).source).toBe("heuristic");
+		const ambiguous = await c.signal("tell me more about it");
+		expect(ambiguous.source).toBe("eliza-1-drafter");
+		expect(ambiguous.model).toContain("mock-eot");
+	});
+});

package/src/services/voice/corpus-augment.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it } from "vitest";
+import {
+	addNoise,
+	applyGainDb,
+	applyLowQualityLine,
+	applyReverb,
+	augmentPcm,
+	dbToGain,
+	estimateSnrDb,
+	measureRms,
+	mixInto,
+	type NoiseKind,
+	specIsClean,
+} from "./corpus-augment";
+
+const SR = 16_000;
+
+/** A deterministic voiced tone with leading + trailing silence. */
+function makeTone(freq: number, durSec: number, gap = 0.2) {
+	const gapN = Math.round(gap * SR);
+	const n = Math.round(durSec * SR) + gapN * 2;
+	const pcm = new Float32Array(n);
+	for (let i = gapN; i < n - gapN; i++) {
+		pcm[i] = 0.5 * Math.sin((2 * Math.PI * freq * (i - gapN)) / SR);
+	}
+	return { pcm, voicedStart: gapN, voicedEnd: n - gapN };
+}
+
+describe("corpus-augment dB helpers", () => {
+	it("dbToGain: +6 dB ≈ ×2, −6 dB ≈ ×0.5", () => {
+		expect(dbToGain(6)).toBeCloseTo(2, 1);
+		expect(dbToGain(-6)).toBeCloseTo(0.5, 1);
+		expect(dbToGain(0)).toBe(1);
+	});
+
+	it("estimateSnrDb recovers a known ratio", () => {
+		expect(estimateSnrDb(1, 0.1)).toBeCloseTo(20, 5);
+		expect(estimateSnrDb(1, 0)).toBe(Number.POSITIVE_INFINITY);
+	});
+});
+
+describe("addNoise", () => {
+	it("hits the target SNR within ~1.5 dB", () => {
+		const { pcm } = makeTone(220, 1.0, 0);
+		const noisy = addNoise(pcm, { snrDb: 10, seed: 1 });
+		// Recover the noise as (noisy − clean) and compare RMS.
+		const noise = new Float32Array(pcm.length);
+		for (let i = 0; i < pcm.length; i++) noise[i] = noisy[i] - pcm[i];
+		const snr = estimateSnrDb(measureRms(pcm), measureRms(noise));
+		expect(snr).toBeGreaterThan(8.5);
+		expect(snr).toBeLessThan(11.5);
+	});
+
+	it("lower SNR is louder noise", () => {
+		const { pcm } = makeTone(220, 0.5, 0);
+		const n5 = addNoise(pcm, { snrDb: 5, seed: 2 });
+		const n20 = addNoise(pcm, { snrDb: 20, seed: 2 });
+		const noise5 = measureRms(n5) - measureRms(pcm);
+		const noise20 = measureRms(n20) - measureRms(pcm);
+		// 5 dB SNR adds more energy than 20 dB SNR.
+		expect(measureRms(n5)).toBeGreaterThan(measureRms(n20));
+		expect(noise5).toBeGreaterThan(noise20);
+	});
+
+	it("is deterministic for a given seed", () => {
+		const { pcm } = makeTone(300, 0.3, 0.1);
+		const a = addNoise(pcm, { snrDb: 8, seed: 42 });
+		const b = addNoise(pcm, { snrDb: 8, seed: 42 });
+		const c = addNoise(pcm, { snrDb: 8, seed: 43 });
+		expect(Array.from(a)).toEqual(Array.from(b));
+		expect(Array.from(a)).not.toEqual(Array.from(c));
+	});
+
+	it("raises the floor in formerly-silent regions", () => {
+		const { pcm, voicedEnd } = makeTone(220, 0.5, 0.2);
+		const tailBefore = measureRms(pcm, voicedEnd);
+		const noisy = addNoise(pcm, { snrDb: 10, seed: 7 });
+		const tailAfter = measureRms(noisy, voicedEnd);
+		expect(tailBefore).toBeLessThan(1e-4);
+		expect(tailAfter).toBeGreaterThan(tailBefore);
+	});
+});
+
+/** Lag-1 normalized autocorrelation: ≈1 for a smooth/tonal signal, ≈0 for
+ * uncorrelated white noise. */
+function lag1Autocorr(x: Float32Array): number {
+	let num = 0;
+	let den = 0;
+	for (let i = 1; i < x.length; i++) num += x[i] * x[i - 1];
+	for (let i = 0; i < x.length; i++) den += x[i] * x[i];
+	return den > 0 ? num / den : 0;
+}
+
+describe("addNoise: music kind", () => {
+	const recoverNoise = (pcm: Float32Array, kind: NoiseKind, seed: number) => {
+		const noisy = addNoise(pcm, { snrDb: 6, kind, seed });
+		const noise = new Float32Array(pcm.length);
+		for (let i = 0; i < pcm.length; i++) noise[i] = noisy[i] - pcm[i];
+		return noise;
+	};
+
+	it("hits the target SNR like the other kinds", () => {
+		const { pcm } = makeTone(220, 1.0, 0);
+		const noise = recoverNoise(pcm, "music", 1);
+		// recoverNoise uses snrDb: 6
+		const snr = estimateSnrDb(measureRms(pcm), measureRms(noise));
+		expect(snr).toBeGreaterThan(4.5);
+		expect(snr).toBeLessThan(7.5);
+	});
+
+	it("is tonal (smooth, highly autocorrelated) unlike flat white noise", () => {
+		const { pcm } = makeTone(220, 0.5, 0);
+		const music = lag1Autocorr(recoverNoise(pcm, "music", 5));
+		const white = lag1Autocorr(recoverNoise(pcm, "white", 5));
+		expect(music).toBeGreaterThan(0.9);
+		expect(white).toBeLessThan(0.5);
+		expect(music).toBeGreaterThan(white);
+	});
+
+	it("is deterministic for a seed and differs from white/pink", () => {
+		const { pcm } = makeTone(300, 0.3, 0.1);
+		const a = addNoise(pcm, { snrDb: 8, kind: "music", seed: 42 });
+		const b = addNoise(pcm, { snrDb: 8, kind: "music", seed: 42 });
+		const white = addNoise(pcm, { snrDb: 8, kind: "white", seed: 42 });
+		const pink = addNoise(pcm, { snrDb: 8, kind: "pink", seed: 42 });
+		expect(Array.from(a)).toEqual(Array.from(b));
+		expect(Array.from(a)).not.toEqual(Array.from(white));
+		expect(Array.from(a)).not.toEqual(Array.from(pink));
+	});
+});
+
+describe("applyReverb", () => {
+	it("spreads energy into the tail after the dry signal ends", () => {
+		const { pcm, voicedEnd } = makeTone(220, 0.4, 0.0);
+		const dryTail = measureRms(pcm, voicedEnd, pcm.length);
+		const wet = applyReverb(pcm, SR, { room: 0.7, wet: 0.6, tailSec: 0.6 });
+		// The reverb output is longer (tail appended) and the post-voice region rings.
+		expect(wet.length).toBeGreaterThan(pcm.length);
+		const wetTail = measureRms(
+			wet,
+			voicedEnd,
+			voicedEnd + Math.round(0.3 * SR),
+		);
+		expect(wetTail).toBeGreaterThan(dryTail);
+		expect(wetTail).toBeGreaterThan(1e-3);
+	});
+
+	it("is deterministic", () => {
+		const { pcm } = makeTone(200, 0.2);
+		const a = applyReverb(pcm, SR, { room: 0.5, wet: 0.4 });
+		const b = applyReverb(pcm, SR, { room: 0.5, wet: 0.4 });
+		expect(Array.from(a)).toEqual(Array.from(b));
+	});
+});
+
+describe("applyGainDb (far-field attenuation)", () => {
+	it("−12 dB quarters the amplitude", () => {
+		const { pcm } = makeTone(220, 0.3, 0);
+		const quiet = applyGainDb(pcm, -12);
+		expect(measureRms(quiet) / measureRms(pcm)).toBeCloseTo(dbToGain(-12), 2);
+	});
+});
+
+describe("applyLowQualityLine", () => {
+	it("attenuates high-frequency content more than the speech band", () => {
+		const band = makeTone(1000, 0.5, 0);
+		const high = makeTone(6500, 0.5, 0);
+		const bandOut = applyLowQualityLine(band.pcm, SR);
+		const highOut = applyLowQualityLine(high.pcm, SR);
+		const bandKept = measureRms(bandOut) / measureRms(band.pcm);
+		const highKept = measureRms(highOut) / measureRms(high.pcm);
+		// 6.5 kHz is above the ~3.4 kHz line cutoff → far more attenuated.
+		expect(highKept).toBeLessThan(bandKept);
+		expect(highKept).toBeLessThan(0.5);
+	});
+
+	it("also strips sub-300 Hz rumble", () => {
+		const low = makeTone(80, 0.5, 0);
+		const out = applyLowQualityLine(low.pcm, SR);
+		expect(measureRms(out) / measureRms(low.pcm)).toBeLessThan(0.6);
+	});
+});
+
+describe("mixInto", () => {
+	it("adds an overlay at the requested level without changing length", () => {
+		const base = new Float32Array(1000);
+		const overlay = new Float32Array(1000).fill(0.5);
+		const mixed = mixInto(base, overlay, { gainDb: -6 });
+		expect(mixed.length).toBe(base.length);
+		expect(mixed[500]).toBeCloseTo(0.5 * dbToGain(-6), 4);
+	});
+
+	it("honors offset and loops a short overlay", () => {
+		const base = new Float32Array(100);
+		const overlay = new Float32Array([1, 0]);
+		const mixed = mixInto(base, overlay, { offsetSamples: 10, loop: true });
+		expect(mixed[9]).toBe(0);
+		expect(mixed[10]).toBe(1);
+		expect(mixed[11]).toBe(0);
+		expect(mixed[12]).toBe(1);
+	});
+
+	it("does not mutate the inputs", () => {
+		const base = new Float32Array([0.125, 0.25]);
+		const overlay = new Float32Array([0.5, 0.5]);
+		mixInto(base, overlay, {});
+		expect(Array.from(base)).toEqual([0.125, 0.25]);
+		expect(Array.from(overlay)).toEqual([0.5, 0.5]);
+	});
+});
+
+describe("augmentPcm chain", () => {
+	it("specIsClean detects a no-op spec", () => {
+		expect(specIsClean(undefined)).toBe(true);
+		expect(specIsClean({})).toBe(true);
+		expect(specIsClean({ noiseKind: "pink" })).toBe(true); // kind alone is a no-op
+		expect(specIsClean({ noiseSnrDb: 10 })).toBe(false);
+		expect(specIsClean({ reverb: 0.5 })).toBe(false);
+		expect(specIsClean({ lowQuality: true })).toBe(false);
+	});
+
+	it("preserves length and stays within [-1, 1]", () => {
+		const { pcm } = makeTone(220, 0.6, 0.15);
+		const out = augmentPcm(
+			pcm,
+			SR,
+			{ noiseSnrDb: 6, reverb: 0.7, farFieldDb: 9, lowQuality: true, seed: 3 },
+			{},
+		);
+		expect(out.length).toBe(pcm.length);
+		let peak = 0;
+		for (const s of out) peak = Math.max(peak, Math.abs(s));
+		expect(peak).toBeLessThanOrEqual(1);
+		expect(out).not.toBe(pcm); // returns a fresh array
+	});
+
+	it("a far-field+reverb+noise voice is materially degraded vs the clean source", () => {
+		const { pcm, voicedStart, voicedEnd } = makeTone(220, 0.8, 0.2);
+		const out = augmentPcm(
+			pcm,
+			SR,
+			{ farFieldDb: 12, reverb: 0.8, noiseSnrDb: 8, seed: 9 },
+			{},
+		);
+		// The voiced region is quieter (far-field) yet the silent tail now has a
+		// noise floor — i.e. SNR dropped, which is the whole point.
+		const cleanVoiced = measureRms(pcm, voicedStart, voicedEnd);
+		const outVoiced = measureRms(out, voicedStart, voicedEnd);
+		expect(outVoiced).toBeLessThan(cleanVoiced);
+		expect(measureRms(out, voicedEnd)).toBeGreaterThan(
+			measureRms(pcm, voicedEnd),
+		);
+	});
+
+	it("mixes background talkers when babble is supplied", () => {
+		const { pcm } = makeTone(220, 0.5, 0.1);
+		const babble = makeTone(440, 0.5, 0).pcm;
+		const withBabble = augmentPcm(
+			pcm,
+			SR,
+			{ backgroundTalkersDb: 6 },
+			{ babble },
+		);
+		const without = augmentPcm(pcm, SR, { backgroundTalkersDb: 6 }, {});
+		// Babble present → louder than the no-babble control (which is a no-op).
+		expect(measureRms(withBabble)).toBeGreaterThan(measureRms(without));
+	});
+
+	it("is fully deterministic end-to-end", () => {
+		const { pcm } = makeTone(220, 0.4, 0.1);
+		const spec = { noiseSnrDb: 7, reverb: 0.5, lowQuality: true, seed: 11 };
+		const a = augmentPcm(pcm, SR, spec, {});
+		const b = augmentPcm(pcm, SR, spec, {});
+		expect(Array.from(a)).toEqual(Array.from(b));
+	});
+});