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

package/src/services/kv-spill.ts

@@ -0,0 +1,357 @@
+/**
+ * CPU-offloaded KV-cache spill policy.
+ *
+ * packages/inference/AGENTS.md §3 item 7 mandates that for context > 64k on a
+ * device whose RAM cannot hold the full KV cache, the runtime MUST implement
+ * *spill* — keep the hot KV pages resident, page the cold ones out to CPU RAM
+ * (or, when even that is insufficient, to disk) — rather than refusing the
+ * request. AGENTS.md §3 "Failure handling" is equally explicit that the spill
+ * is gated by a real latency budget: a device where paging the cold KV back in
+ * would miss the voice first-audio-latency target must HARD-FAIL with a
+ * structured error, not silently serve a slow session.
+ *
+ * This module is the policy core. It is pure arithmetic — no llama-server
+ * process management, no native binding. `ffi-streaming-backend.ts` consults
+ * `planKvSpill()` at activation time:
+ *   - `mode: "resident"`  → no spill needed; load normally.
+ *   - `mode: "spill"`     → pass the resulting `residentPages` /
+ *                           `spillBytes` / tier ("cpu" | "disk") down to the
+ *                           backend as a `--kv-spill` hint.
+ *   - `mode: "unsupported"` → throw `KvSpillUnsupportedError` so the engine
+ *                           surfaces a structured 4xx to the UI.
+ *
+ * Model parameters (page size, per-page bandwidth, voice latency budget) are
+ * documented constants below — the only "measured" inputs are the device's
+ * memory bandwidth class and the KV geometry of the loaded bundle. We do not
+ * pretend to micro-benchmark the disk here; the bandwidth tiers are coarse
+ * and conservative, and the gate fails *closed*.
+ */
+
+import type { RamBudget } from "./types";
+
+/** Context length below which spill never applies (AGENTS.md §3 item 7). */
+export const KV_SPILL_MIN_CONTEXT = 65536;
+
+/**
+ * KV-cache page granularity, in tokens. The runtime evicts/restores KV in
+ * page units, not per-token, so spill accounting is page-aligned. 256 tokens
+ * is the buun-llama-cpp fork's default `--kv-page-size` for the spillable
+ * cache; keep this in sync if that default changes.
+ */
+export const KV_PAGE_TOKENS = 256;
+
+/**
+ * First-audio-latency budget for voice mode, in milliseconds. The streaming
+ * contract (AGENTS.md §4) wants the phrase chunker handing the first chunk to
+ * TTS inside a scheduler tick; a cold KV restore at decode time eats directly
+ * into this budget. If the worst-case restore for the spilled pages exceeds
+ * this, spill is not viable for a voice-enabled bundle and we hard-fail.
+ *
+ * Text-only bundles get the looser `KV_SPILL_TEXT_LATENCY_BUDGET_MS`.
+ */
+export const KV_SPILL_VOICE_LATENCY_BUDGET_MS = 200;
+export const KV_SPILL_TEXT_LATENCY_BUDGET_MS = 1500;
+
+/**
+ * Effective KV transfer bandwidth back into the attention kernel, by storage
+ * tier and host class, in bytes per millisecond (≈ GB/s). Conservative — the
+ * gate fails closed, so under-estimating bandwidth only makes us refuse more
+ * aggressively, never serve something too slow.
+ *
+ *   - `cpu`/`apple` : Apple Silicon shared memory — "spilling to CPU" is
+ *                     mostly an accounting move (same physical RAM, different
+ *                     residency bookkeeping); effective restore bandwidth is
+ *                     high.
+ *   - `cpu`/`pcie`  : discrete-GPU x86 — cold KV pages live in host RAM and
+ *                     ride the PCIe bus back to VRAM. PCIe 4.0 x16 ≈ 25 GB/s
+ *                     after framing; we budget 12.
+ *   - `disk`/`nvme` : NVMe SSD — sequential read ≈ 3 GB/s; we budget 1.5.
+ *   - `disk`/`sata` : SATA SSD / spinning rust fallback — ≈ 0.4 GB/s; we
+ *                     budget 0.25. (Mostly here so the math is defined; in
+ *                     practice this tier fails the gate immediately.)
+ */
+const KV_RESTORE_BANDWIDTH_BYTES_PER_MS = {
+	"cpu-apple": 40_000_000,
+	"cpu-pcie": 12_000_000,
+	"disk-nvme": 1_500_000,
+	"disk-sata": 250_000,
+} as const;
+
+export type KvRestoreClass = keyof typeof KV_RESTORE_BANDWIDTH_BYTES_PER_MS;
+
+/**
+ * Per-token KV-cache footprint of a loaded bundle, summed across all
+ * full-attention layers, for the *quantized* cache it actually ships with
+ * (QJL K + PolarQuant/TurboQuant V — see packages/training/AGENTS.md §3).
+ * Callers derive this from the bundle's manifest / catalog runtime block;
+ * `estimateQuantizedKvBytesPerToken()` is the fallback when only the param
+ * count is known.
+ */
+export interface KvGeometry {
+	/** Bytes of compressed KV the cache grows by, per generated token. */
+	bytesPerToken: number;
+	/** True when the loaded bundle has voice enabled (tighter latency gate). */
+	voiceEnabled: boolean;
+}
+
+/**
+ * Fallback per-token KV estimate when the manifest doesn't carry an explicit
+ * figure. Order-of-magnitude only. Gemma 4 E2B uses stock q8_0 KV over an MQA
+ * geometry (n_head_kv=1) with dual head dims — 512 global / 256 SWA — summed
+ * over the global + sliding-window attention layers. For Gemma-4-class
+ * geometry that lands roughly at the table below (bytes/token across the whole
+ * cache). These are the figures the catalog's per-tier `ramBudgetMb` was sized
+ * against.
+ */
+const QUANTIZED_KV_BYTES_PER_TOKEN_BY_PARAMS: Readonly<Record<string, number>> =
+	{
+		"0.8B": 1_400,
+		"2B": 2_400,
+		"4B": 4_800,
+		"9B": 9_000,
+		"27B": 22_000,
+	};
+
+export function estimateQuantizedKvBytesPerToken(params: string): number {
+	const known = QUANTIZED_KV_BYTES_PER_TOKEN_BY_PARAMS[params];
+	if (known !== undefined) return known;
+	// Unknown param string — fail closed by assuming the largest tier's
+	// footprint so a mis-tagged bundle errs toward refusing spill rather than
+	// toward over-promising residency.
+	return QUANTIZED_KV_BYTES_PER_TOKEN_BY_PARAMS["27B"];
+}
+
+/**
+ * Where the spilled pages land. `"cpu"` = host RAM (still RAM, just not
+ * counted against the resident budget); `"disk"` = the local-inference cache
+ * directory on persistent storage.
+ */
+export type KvSpillTier = "cpu" | "disk";
+
+export interface KvSpillPlanResident {
+	mode: "resident";
+	/** The whole KV cache fits in the resident budget; nothing spills. */
+	totalKvBytes: number;
+	residentBytes: number;
+}
+
+export interface KvSpillPlanSpill {
+	mode: "spill";
+	tier: KvSpillTier;
+	/** Pages kept resident (the hot tail of the context). */
+	residentPages: number;
+	/** Pages paged out to `tier`. */
+	spillPages: number;
+	/** Bytes of KV held resident. */
+	residentBytes: number;
+	/** Bytes of KV spilled to `tier`. */
+	spillBytes: number;
+	/** Total compressed KV footprint at full context. */
+	totalKvBytes: number;
+	/** Worst-case latency to restore one cold page, in ms. */
+	worstCaseRestoreMs: number;
+	/** The latency budget this plan was checked against, in ms. */
+	latencyBudgetMs: number;
+}
+
+export type KvSpillPlan = KvSpillPlanResident | KvSpillPlanSpill;
+
+/**
+ * Structured error thrown when spill cannot meet the latency budget. The
+ * engine catches this and surfaces it to the UI as a 4xx with `code` and
+ * `details` intact — there is NO silent-slow fallback (AGENTS.md §3).
+ */
+export class KvSpillUnsupportedError extends Error {
+	readonly code = "kv-spill-unsupported";
+	readonly details: {
+		requestedContext: number;
+		totalKvBytes: number;
+		residentBytes: number;
+		spillBytes: number;
+		worstCaseRestoreMs: number;
+		latencyBudgetMs: number;
+		restoreClass: KvRestoreClass;
+		voiceEnabled: boolean;
+	};
+
+	constructor(details: KvSpillUnsupportedError["details"]) {
+		super(
+			`KV-cache spill for a ${details.requestedContext}-token context cannot ` +
+				`meet the ${
+					details.voiceEnabled ? "voice" : "text"
+				} latency budget on this device: worst-case cold-page restore is ` +
+				`${details.worstCaseRestoreMs.toFixed(1)}ms vs a ${
+					details.latencyBudgetMs
+				}ms budget (${details.restoreClass}, ${(
+					details.spillBytes / 1024 / 1024
+				).toFixed(0)} MiB would spill). Use a smaller context variant or a ` +
+				`device with more RAM / faster storage.`,
+		);
+		this.name = "KvSpillUnsupportedError";
+		this.details = details;
+	}
+}
+
+/**
+ * Inputs to `planKvSpill`. `residentKvBudgetBytes` is the slice of the RAM
+ * budget the runtime is willing to hand to the *resident* KV cache after
+ * weights + activations + the TTS/ASR working sets are accounted for; callers
+ * derive it from `RamBudget` via `residentKvBudgetFromRamBudget()`.
+ */
+export interface KvSpillInput {
+	requestedContext: number;
+	geometry: KvGeometry;
+	residentKvBudgetBytes: number;
+	restoreClass: KvRestoreClass;
+	/**
+	 * True when the host can spill to CPU RAM (host RAM available beyond the
+	 * resident budget). When false the spill tier degrades to `"disk"`.
+	 */
+	cpuSpillAvailable: boolean;
+}
+
+/**
+ * Slice the resident-KV budget out of a model's `RamBudget`. The recommended
+ * budget covers weights + activations + voice working sets + KV; we reserve a
+ * fixed fraction for KV. This mirrors what `recommendation.ts` already assumes
+ * implicitly when it sizes tiers — kept as one constant so the spill policy
+ * and the recommender agree.
+ */
+export const RESIDENT_KV_BUDGET_FRACTION = 0.25;
+
+export function residentKvBudgetFromRamBudget(budget: RamBudget): number {
+	return Math.floor(
+		budget.recommendedMb * 1024 * 1024 * RESIDENT_KV_BUDGET_FRACTION,
+	);
+}
+
+function pagesForTokens(tokens: number): number {
+	return Math.ceil(tokens / KV_PAGE_TOKENS);
+}
+
+/**
+ * Decide the KV-cache placement for a requested context.
+ *
+ * Returns `{ mode: "resident" }` when the whole compressed KV fits the
+ * resident budget; `{ mode: "spill", ... }` when it fits with paging and the
+ * cold-page restore stays inside the latency budget; throws
+ * `KvSpillUnsupportedError` when spill would miss the budget.
+ *
+ * Below `KV_SPILL_MIN_CONTEXT` this is always `{ mode: "resident" }` — there
+ * is no spill at short context, by contract.
+ */
+export function planKvSpill(input: KvSpillInput): KvSpillPlan {
+	const { requestedContext, geometry, residentKvBudgetBytes } = input;
+
+	if (
+		!Number.isFinite(requestedContext) ||
+		requestedContext <= 0 ||
+		!Number.isFinite(geometry.bytesPerToken) ||
+		geometry.bytesPerToken <= 0
+	) {
+		throw new Error(
+			`[kv-spill] planKvSpill needs a positive context and bytesPerToken; got context=${requestedContext}, bytesPerToken=${geometry.bytesPerToken}`,
+		);
+	}
+	if (residentKvBudgetBytes <= 0) {
+		throw new Error(
+			`[kv-spill] residentKvBudgetBytes must be positive; got ${residentKvBudgetBytes}`,
+		);
+	}
+
+	const pageBytes = geometry.bytesPerToken * KV_PAGE_TOKENS;
+	const totalPages = pagesForTokens(requestedContext);
+	const totalKvBytes = totalPages * pageBytes;
+
+	// Whole cache fits resident — no spill, regardless of context length.
+	if (totalKvBytes <= residentKvBudgetBytes) {
+		return {
+			mode: "resident",
+			totalKvBytes,
+			residentBytes: totalKvBytes,
+		};
+	}
+
+	// Below the contract floor, spill is not on the table: a 64k-or-less
+	// context that doesn't fit the resident budget is a wrong-tier-for-device
+	// situation, not a spill case. The recommender's RAM gate should have
+	// already excluded this; treat it as unsupported with the same structured
+	// error so the engine surfaces it cleanly rather than half-loading.
+	if (requestedContext < KV_SPILL_MIN_CONTEXT) {
+		throw new KvSpillUnsupportedError({
+			requestedContext,
+			totalKvBytes,
+			residentBytes: residentKvBudgetBytes,
+			spillBytes: totalKvBytes - residentKvBudgetBytes,
+			worstCaseRestoreMs: 0,
+			latencyBudgetMs: 0,
+			restoreClass: input.restoreClass,
+			voiceEnabled: geometry.voiceEnabled,
+		});
+	}
+
+	const residentPages = Math.max(
+		1,
+		Math.floor(residentKvBudgetBytes / pageBytes),
+	);
+	const spillPages = totalPages - residentPages;
+	const residentBytes = residentPages * pageBytes;
+	const spillBytes = spillPages * pageBytes;
+
+	const tier: KvSpillTier = input.cpuSpillAvailable ? "cpu" : "disk";
+	// When CPU spill isn't available the only restore class that makes sense is
+	// a disk one; if the caller handed us a `cpu-*` class, downgrade to NVMe.
+	const restoreClass: KvRestoreClass =
+		tier === "disk" && input.restoreClass.startsWith("cpu-")
+			? "disk-nvme"
+			: input.restoreClass;
+	const bandwidth = KV_RESTORE_BANDWIDTH_BYTES_PER_MS[restoreClass];
+
+	// Worst case at decode time: a single cold page faulted back in. (Spilling
+	// by page keeps this bounded — a smaller `KV_PAGE_TOKENS` is the lever for
+	// cutting the worst case if a device class needs it.)
+	const worstCaseRestoreMs = pageBytes / bandwidth;
+	const latencyBudgetMs = geometry.voiceEnabled
+		? KV_SPILL_VOICE_LATENCY_BUDGET_MS
+		: KV_SPILL_TEXT_LATENCY_BUDGET_MS;
+
+	if (worstCaseRestoreMs > latencyBudgetMs) {
+		throw new KvSpillUnsupportedError({
+			requestedContext,
+			totalKvBytes,
+			residentBytes,
+			spillBytes,
+			worstCaseRestoreMs,
+			latencyBudgetMs,
+			restoreClass,
+			voiceEnabled: geometry.voiceEnabled,
+		});
+	}
+
+	return {
+		mode: "spill",
+		tier,
+		residentPages,
+		spillPages,
+		residentBytes,
+		spillBytes,
+		totalKvBytes,
+		worstCaseRestoreMs,
+		latencyBudgetMs,
+	};
+}
+
+/**
+ * Map a `HardwareProbe`-shaped descriptor to the KV restore bandwidth class.
+ * Apple Silicon → unified-memory class; discrete-GPU x86 → PCIe class;
+ * CPU-only → NVMe class (no GPU to page back to, so "restore" is a host-RAM
+ * memcpy bounded by the same order as a fast SSD on the conservative side).
+ */
+export function restoreClassForHardware(input: {
+	appleSilicon: boolean;
+	hasDiscreteGpu: boolean;
+}): KvRestoreClass {
+	if (input.appleSilicon) return "cpu-apple";
+	if (input.hasDiscreteGpu) return "cpu-pcie";
+	return "disk-nvme";
+}

package/src/services/latency-trace.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "vitest";
+import {
+	buildVoiceLatencyDevPayload,
+	EndToEndLatencyTracer,
+	LATENCY_DERIVED_KEYS,
+	VOICE_CHECKPOINTS,
+	type VoiceCheckpoint,
+} from "./latency-trace";
+import type { VadEvent, VadEventListener } from "./voice/types";
+
+/** Drive one full turn's worth of checkpoints with explicit timestamps. */
+function fullTurn(
+	tracer: EndToEndLatencyTracer,
+	base: number,
+	offsets: Partial<Record<VoiceCheckpoint, number>>,
+	roomId?: string,
+): string {
+	const turnId = tracer.beginTurn(roomId ? { roomId } : {});
+	for (const cp of VOICE_CHECKPOINTS) {
+		const off = offsets[cp];
+		if (off === undefined) continue;
+		tracer.mark(turnId, cp, base + off);
+	}
+	return turnId;
+}
+
+const CANONICAL_OFFSETS: Record<VoiceCheckpoint, number> = {
+	"peer-utterance-end": -120,
+	"vad-trigger": 0,
+	"vad-speech-start": 30,
+	"prewarm-fired": 35,
+	"asr-first-partial": 220,
+	"asr-final": 900,
+	"llm-first-token": 1000,
+	"llm-first-replytext-char": 1040,
+	"replyText-first-emotion-tag": 1050,
+	"phrase-1-to-tts": 1090,
+	"tts-first-audio-chunk": 1200,
+	"audio-first-played": 1230,
+	"audio-first-into-peer-ring": 1235,
+};
+
+describe("EndToEndLatencyTracer", () => {
+	it("records checkpoints and derives metrics for a complete turn", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = fullTurn(tracer, 1_000_000, CANONICAL_OFFSETS, "roomA");
+		const trace = tracer.endTurn(turnId);
+		expect(trace).not.toBeNull();
+		if (!trace) return;
+		expect(trace.complete).toBe(true);
+		// CANONICAL_OFFSETS records every checkpoint including the duet-only ones,
+		// so nothing is missing.
+		expect(trace.missing).toHaveLength(0);
+		expect(trace.roomId).toBe("roomA");
+		expect(trace.checkpoints).toHaveLength(VOICE_CHECKPOINTS.length);
+		// t0 == the earliest checkpoint recorded — here `peer-utterance-end`
+		// (offset -120), the duet headline t0; checkpoints sorted by atEpochMs.
+		expect(trace.t0EpochMs).toBe(1_000_000 - 120);
+		expect(trace.checkpoints[0]?.name).toBe("peer-utterance-end");
+		expect(trace.checkpoints[0]?.tMs).toBe(0);
+		// Derived spans (absolute deltas — independent of t0).
+		expect(trace.derived.ttftMs).toBe(1000); // vad-trigger → llm-first-token
+		expect(trace.derived.ttfaMs).toBe(1200); // vad-trigger → tts-first-audio-chunk
+		expect(trace.derived.ttapMs).toBe(1230); // vad-trigger → audio-first-played
+		expect(trace.derived.asrFinalLatencyMs).toBe(870); // vad-speech-start(30) → asr-final(900)
+		expect(trace.derived.prewarmLatencyMs).toBe(35);
+		expect(trace.derived.audioSinkLatencyMs).toBe(30); // tts-first-chunk(1200) → played(1230)
+		// Duet (cross-agent) spans — peer-utterance-end(-120) is the headline t0.
+		expect(trace.derived.ttftFromUtteranceEndMs).toBe(1120); // -120 → 1000
+		expect(trace.derived.firstAudioIntoPeerRingFromUtteranceEndMs).toBe(1355); // -120 → 1235
+		expect(trace.derived.emotionTagOverheadMs).toBe(50); // llm-first-token(1000) → tag(1050)
+		expect(trace.anomalies).toHaveLength(0);
+	});
+
+	it("leaves derived metrics null when an endpoint checkpoint is missing", () => {
+		const tracer = new EndToEndLatencyTracer();
+		// No `audio-first-played`, no `tts-first-audio-chunk`.
+		const offsets = { ...CANONICAL_OFFSETS };
+		delete (offsets as Partial<Record<VoiceCheckpoint, number>>)[
+			"tts-first-audio-chunk"
+		];
+		delete (offsets as Partial<Record<VoiceCheckpoint, number>>)[
+			"audio-first-played"
+		];
+		const turnId = fullTurn(tracer, 2_000_000, offsets);
+		const trace = tracer.endTurn(turnId);
+		if (!trace) throw new Error("expected trace");
+		expect(trace.complete).toBe(false);
+		expect(trace.missing).toEqual(
+			expect.arrayContaining(["tts-first-audio-chunk", "audio-first-played"]),
+		);
+		expect(trace.derived.ttftMs).toBe(1000); // still computable
+		expect(trace.derived.ttfaMs).toBeNull(); // depends on tts-first-audio-chunk
+		expect(trace.derived.ttapMs).toBeNull(); // depends on audio-first-played
+		expect(trace.derived.audioSinkLatencyMs).toBeNull();
+	});
+
+	it("flags a duplicate mark and keeps the first timestamp", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = tracer.beginTurn({});
+		tracer.mark(turnId, "vad-trigger", 100);
+		tracer.mark(turnId, "vad-trigger", 999); // duplicate
+		tracer.mark(turnId, "llm-first-token", 600);
+		const trace = tracer.endTurn(turnId);
+		if (!trace) throw new Error("expected trace");
+		expect(trace.anomalies.some((a) => a.includes("duplicate"))).toBe(true);
+		expect(trace.derived.ttftMs).toBe(500); // 100 → 600, not 999 → 600
+	});
+
+	it("flags an out-of-order checkpoint without reordering", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = tracer.beginTurn({});
+		tracer.mark(turnId, "vad-trigger", 100);
+		tracer.mark(turnId, "llm-first-token", 500);
+		// asr-final ordered before llm-first-token but timestamped after it.
+		tracer.mark(turnId, "asr-final", 700);
+		const trace = tracer.endTurn(turnId);
+		if (!trace) throw new Error("expected trace");
+		expect(trace.anomalies.some((a) => a.includes("clock skew"))).toBe(true);
+		expect(trace.derived.llmFirstTokenAfterAsrMs).toBe(-200); // 700 → 500 recorded as-is
+	});
+
+	it("ignores marks for unknown / closed turns", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = tracer.beginTurn({});
+		tracer.mark(turnId, "vad-trigger", 1);
+		tracer.endTurn(turnId);
+		// Late mark — must not throw, must not resurrect the turn.
+		tracer.mark(turnId, "llm-first-token", 5);
+		tracer.mark("does-not-exist", "vad-trigger", 5);
+		expect(tracer.recentTraces()).toHaveLength(1);
+	});
+
+	it("evicts the oldest trace when the ring is full", () => {
+		const tracer = new EndToEndLatencyTracer({ ringCapacity: 3 });
+		for (let i = 0; i < 5; i += 1) {
+			const turnId = tracer.beginTurn({ roomId: `room-${i}` });
+			tracer.mark(turnId, "vad-trigger", i * 1000);
+			tracer.mark(turnId, "llm-first-token", i * 1000 + 100);
+			tracer.endTurn(turnId);
+		}
+		const traces = tracer.recentTraces();
+		expect(traces).toHaveLength(3);
+		expect(traces.map((t) => t.roomId)).toEqual(["room-2", "room-3", "room-4"]);
+	});
+
+	it("evicts the oldest *open* turn past maxOpenTurns", () => {
+		const tracer = new EndToEndLatencyTracer({ maxOpenTurns: 2 });
+		const a = tracer.beginTurn({ roomId: "a" });
+		tracer.mark(a, "vad-trigger", 10);
+		tracer.beginTurn({ roomId: "b" });
+		tracer.beginTurn({ roomId: "c" }); // forces eviction of `a`
+		expect(tracer.openTurnCount).toBe(2);
+		// `a` was emitted with whatever it had.
+		const traces = tracer.recentTraces();
+		expect(traces.some((t) => t.roomId === "a")).toBe(true);
+		// A mark on the evicted turn is now ignored.
+		tracer.mark(a, "llm-first-token", 50);
+		expect(
+			tracer.recentTraces().find((t) => t.roomId === "a")?.missing,
+		).toContain("llm-first-token");
+	});
+
+	it("builds histograms with nearest-rank percentiles", () => {
+		const tracer = new EndToEndLatencyTracer();
+		// Five turns with ttftMs of 100, 200, 300, 400, 500.
+		for (const v of [100, 200, 300, 400, 500]) {
+			const turnId = tracer.beginTurn({});
+			tracer.mark(turnId, "vad-trigger", 0);
+			tracer.mark(turnId, "llm-first-token", v);
+			tracer.endTurn(turnId);
+		}
+		const h = tracer.histogramSummaries();
+		expect(h.ttftMs.count).toBe(5);
+		expect(h.ttftMs.min).toBe(100);
+		expect(h.ttftMs.max).toBe(500);
+		expect(h.ttftMs.p50).toBe(300);
+		expect(h.ttftMs.p90).toBe(500);
+		expect(h.ttftMs.p99).toBe(500);
+		expect(h.ttftMs.mean).toBe(300);
+		// A metric with no samples is all-null, not zero.
+		expect(h.ttfaMs.count).toBe(0);
+		expect(h.ttfaMs.p50).toBeNull();
+	});
+
+	it("only feeds non-null derived metrics into the histograms", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = tracer.beginTurn({});
+		tracer.mark(turnId, "vad-trigger", 0);
+		// No llm-first-token → ttftMs is null and must not become a 0 sample.
+		tracer.mark(turnId, "asr-first-partial", 150);
+		tracer.endTurn(turnId);
+		const h = tracer.histogramSummaries();
+		expect(h.ttftMs.count).toBe(0);
+		expect(h.asrFirstPartialMs.count).toBe(1);
+		expect(h.asrFirstPartialMs.p50).toBe(150);
+	});
+
+	it("bridges a VadEventSource onto vad-trigger / vad-speech-start", () => {
+		const listeners = new Set<VadEventListener>();
+		const source = {
+			onVadEvent(l: VadEventListener) {
+				listeners.add(l);
+				return () => listeners.delete(l);
+			},
+		};
+		const emit = (e: VadEvent) => {
+			for (const l of listeners) l(e);
+		};
+		const tracer = new EndToEndLatencyTracer();
+		let openedTurnId: string | null = null;
+		const unsub = tracer.bindVadDetector(source, {
+			roomId: "roomVad",
+			onTurnOpen: (id) => {
+				openedTurnId = id;
+			},
+		});
+		emit({ type: "speech-start", timestampMs: 4_242, probability: 0.9 });
+		expect(openedTurnId).not.toBeNull();
+		if (!openedTurnId) return;
+		// The bridge recorded vad-trigger + vad-speech-start at the event ts.
+		const peek = tracer.peekTurn(openedTurnId);
+		expect(peek?.checkpoints.map((c) => c.name)).toEqual([
+			"vad-trigger",
+			"vad-speech-start",
+		]);
+		expect(peek?.t0EpochMs).toBe(4_242);
+		// speech-active / speech-end do not open new turns.
+		emit({
+			type: "speech-active",
+			timestampMs: 4_500,
+			probability: 0.95,
+			speechDurationMs: 258,
+		});
+		expect(tracer.openTurnCount).toBe(1);
+		unsub();
+		emit({ type: "speech-start", timestampMs: 9_000, probability: 0.8 });
+		// After unsubscribe, no new turn.
+		expect(tracer.openTurnCount).toBe(1);
+	});
+
+	it("buildVoiceLatencyDevPayload exposes traces + histograms + metadata", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const turnId = fullTurn(tracer, 5_000_000, CANONICAL_OFFSETS, "roomP");
+		tracer.endTurn(turnId);
+		const payload = buildVoiceLatencyDevPayload(tracer, 10);
+		expect(payload.checkpoints).toEqual(VOICE_CHECKPOINTS);
+		expect(payload.derivedKeys).toEqual(LATENCY_DERIVED_KEYS);
+		expect(payload.openTurnCount).toBe(0);
+		expect(payload.traces).toHaveLength(1);
+		expect(payload.traces[0]?.roomId).toBe("roomP");
+		expect(payload.histograms.ttftMs.count).toBe(1);
+		expect(typeof payload.generatedAtEpochMs).toBe("number");
+	});
+
+	it("reset() clears traces, histograms, and open turns", () => {
+		const tracer = new EndToEndLatencyTracer();
+		const t = fullTurn(tracer, 1, CANONICAL_OFFSETS);
+		tracer.endTurn(t);
+		tracer.beginTurn({ roomId: "still-open" });
+		tracer.reset();
+		expect(tracer.recentTraces()).toHaveLength(0);
+		expect(tracer.openTurnCount).toBe(0);
+		expect(tracer.histogramSummaries().ttftMs.count).toBe(0);
+	});
+});