@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

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

@@ -0,0 +1,346 @@
+/**
+ * End-to-end voice-loop latency tracing.
+ *
+ * One `LatencyTrace` per voice turn — a span recorder with named
+ * checkpoints from "user makes a sound" to "agent's first audio plays".
+ * The checkpoint set is fixed (`VOICE_CHECKPOINTS`) and ordered; each
+ * checkpoint is recorded at most once per turn. Missing checkpoints are
+ * surfaced as missing-checkpoint state — never synthesized — and derived
+ * metrics that depend on a missing checkpoint stay `null` (AGENTS.md §3 / §7:
+ * a missing measurement is recorded as missing, not faked).
+ *
+ * Ownership / lifecycle:
+ *   - The turn controller (`voice/turn-controller.ts`, W9) is the natural
+ *     owner of the per-turn tracer: it calls `tracer.beginTurn({...})` when
+ *     a turn opens and `tracer.endTurn(turnId)` when it finalizes/aborts.
+ *     Until that lands, callers can use the module-level
+ *     `voiceLatencyTracer` singleton + the `markVoiceLatency()` helper —
+ *     the singleton lazily opens a turn keyed by `roomId` on first mark.
+ *   - Components that produce a checkpoint either (a) hold a `tracer` and
+ *     call `tracer.mark(turnId, checkpoint)`, or (b) call the context-free
+ *     `markVoiceLatency(roomId, checkpoint)` helper. `bindVadDetector()`
+ *     bridges a `VadEventSource` onto the tracer without touching `vad.ts`.
+ *
+ * Hook points (where each checkpoint is meant to be recorded):
+ *   - `peer-utterance-end`       — (DUET ONLY) the producing agent's
+ *                                   scheduler drained its last PCM chunk into
+ *                                   the cross ring — the headline `t0` for a
+ *                                   two-agents-talking run (`voice-duet.mjs`).
+ *                                   Not recorded in the single-agent path.
+ *   - `vad-trigger`              — `VadDetector` energy-rise edge / the
+ *                                   turn controller's wake instant.
+ *   - `vad-speech-start`         — `VadDetector` Silero speech-start.
+ *   - `prewarm-fired`            — the turn controller (W9) when it calls
+ *                                   W6's `prewarmConversation`.
+ *   - `asr-first-partial`        — `StreamingTranscriber` first `partial`.
+ *   - `asr-final`                — `StreamingTranscriber` `final`.
+ *   - `llm-first-token`          — the engine generate path's first
+ *                                   `onTextChunk` (W4).
+ *   - `llm-first-replytext-char` — `StructuredFieldStreamExtractor`'s
+ *                                   `onFieldStart("replyText")`.
+ *   - `replyText-first-emotion-tag` — the field extractor / `parseExpressiveTags`
+ *                                   on the first inline expressive tag (`[happy]`
+ *                                   …) in `replyText` — emotion-markup overhead,
+ *                                   measured the way `envelopeToReplyTextMs`
+ *                                   measures envelope overhead.
+ *   - `phrase-1-to-tts`          — the scheduler/chunker (W9) on the first
+ *                                   phrase handed to the TTS backend.
+ *   - `tts-first-audio-chunk`    — the TTS backend's first PCM chunk (W7).
+ *   - `audio-first-played`       — the audio sink on the first written
+ *                                   sample (W9/W13) — single-agent path.
+ *   - `audio-first-into-peer-ring` — (DUET ONLY) the responding agent's first
+ *                                   TTS PCM chunk landed in the peer's ring
+ *                                   (the duet replacement for
+ *                                   `audio-first-played` — no speakers).
+ *
+ * Logger only, `[LatencyTracer]` prefix (AGENTS.md §9).
+ */
+import type { VadEventSource } from "./voice/types";
+/**
+ * The fixed, ordered set of latency checkpoints. The recorder enforces the
+ * order is non-decreasing in wall-clock terms only loosely — a checkpoint
+ * arriving "out of order" (a later checkpoint with an earlier timestamp) is
+ * recorded as-is and flagged; we never reorder or clamp.
+ */
+export declare const VOICE_CHECKPOINTS: readonly ["peer-utterance-end", "vad-trigger", "vad-speech-start", "prewarm-fired", "asr-first-partial", "asr-final", "llm-first-token", "llm-first-replytext-char", "replyText-first-emotion-tag", "phrase-1-to-tts", "tts-first-audio-chunk", "audio-first-played", "audio-first-into-peer-ring"];
+export type VoiceCheckpoint = (typeof VOICE_CHECKPOINTS)[number];
+/** The single-agent "core" checkpoint set — every checkpoint that is NOT
+ *  optional. A trace is `complete` iff every core checkpoint was recorded. */
+export declare const CORE_VOICE_CHECKPOINTS: ("peer-utterance-end" | "vad-trigger" | "vad-speech-start" | "prewarm-fired" | "asr-first-partial" | "asr-final" | "llm-first-token" | "llm-first-replytext-char" | "replyText-first-emotion-tag" | "phrase-1-to-tts" | "tts-first-audio-chunk" | "audio-first-played" | "audio-first-into-peer-ring")[];
+/**
+ * Derived per-turn metrics. Every field is the duration between two
+ * checkpoints; `null` whenever either endpoint checkpoint is missing for
+ * the turn — there is no fallback estimate.
+ */
+export interface LatencyDerived {
+    /** vad-trigger → llm-first-token (time-to-first-token). */
+    ttftMs: number | null;
+    /** vad-trigger → tts-first-audio-chunk (time-to-first-audio). */
+    ttfaMs: number | null;
+    /** vad-trigger → audio-first-played (time-to-audio-played; the headline). */
+    ttapMs: number | null;
+    /** vad-speech-start → asr-final (ASR finalization latency). */
+    asrFinalLatencyMs: number | null;
+    /** vad-trigger → asr-first-partial (how fast the first words appear). */
+    asrFirstPartialMs: number | null;
+    /** vad-trigger → prewarm-fired (how fast the prewarm kicks off). */
+    prewarmLatencyMs: number | null;
+    /** asr-final → llm-first-token (LLM latency once the prompt is complete). */
+    llmFirstTokenAfterAsrMs: number | null;
+    /** llm-first-token → llm-first-replytext-char (envelope-skip overhead). */
+    envelopeToReplyTextMs: number | null;
+    /** llm-first-replytext-char → phrase-1-to-tts (chunker hand-off lag). */
+    replyTextToPhrase1Ms: number | null;
+    /** phrase-1-to-tts → tts-first-audio-chunk (TTS first-chunk latency). */
+    ttsFirstChunkMs: number | null;
+    /** tts-first-audio-chunk → audio-first-played (sink/playback lag). */
+    audioSinkLatencyMs: number | null;
+    /**
+     * peer-utterance-end → llm-first-token — **THE headline number** for the
+     * two-agents-talking benchmark: how long after the peer stopped speaking
+     * the responding agent emits its first token (TTFT-from-last-utterance).
+     */
+    ttftFromUtteranceEndMs: number | null;
+    /** peer-utterance-end → llm-first-replytext-char. */
+    replyTextFirstCharFromUtteranceEndMs: number | null;
+    /** peer-utterance-end → tts-first-audio-chunk. */
+    firstTtsPcmFromUtteranceEndMs: number | null;
+    /**
+     * peer-utterance-end → audio-first-into-peer-ring — the **duet round-trip**:
+     * peer stops speaking → responding agent's first audio is back in the
+     * peer's ear (the `duet_round_trip_ms` gate reads `.p50` of this).
+     */
+    firstAudioIntoPeerRingFromUtteranceEndMs: number | null;
+    /** llm-first-token → replyText-first-emotion-tag (emotion-markup overhead);
+     *  `null` when the model emitted no inline expressive tag. */
+    emotionTagOverheadMs: number | null;
+}
+/** The derived-metric keys, in display order. */
+export declare const LATENCY_DERIVED_KEYS: readonly ["ttftFromUtteranceEndMs", "firstAudioIntoPeerRingFromUtteranceEndMs", "ttftMs", "ttfaMs", "ttapMs", "asrFinalLatencyMs", "asrFirstPartialMs", "prewarmLatencyMs", "llmFirstTokenAfterAsrMs", "envelopeToReplyTextMs", "emotionTagOverheadMs", "replyTextToPhrase1Ms", "ttsFirstChunkMs", "audioSinkLatencyMs", "ttftFromUtteranceEndMs", "replyTextFirstCharFromUtteranceEndMs", "firstTtsPcmFromUtteranceEndMs", "firstAudioIntoPeerRingFromUtteranceEndMs", "emotionTagOverheadMs"];
+export type LatencyDerivedKey = (typeof LATENCY_DERIVED_KEYS)[number];
+export interface LatencyCheckpoint {
+    name: VoiceCheckpoint;
+    /** Wall-clock ms since the turn's `t0` (the first checkpoint recorded). */
+    tMs: number;
+    /** Absolute epoch ms when the checkpoint was recorded. */
+    atEpochMs: number;
+}
+export interface LatencyTrace {
+    turnId: string;
+    roomId: string | null;
+    /** Epoch ms of the first checkpoint recorded for this turn (the t=0 ref). */
+    t0EpochMs: number;
+    /** Epoch ms when `endTurn` was called, or null while still open. */
+    closedAtEpochMs: number | null;
+    checkpoints: LatencyCheckpoint[];
+    derived: LatencyDerived;
+    /** Names of checkpoints that were never recorded for this turn. */
+    missing: VoiceCheckpoint[];
+    /** True when every checkpoint in `VOICE_CHECKPOINTS` was recorded. */
+    complete: boolean;
+    /**
+     * Non-empty when the recorder saw something it could not reconcile —
+     * a duplicate mark, an out-of-order timestamp, an unknown checkpoint.
+     * Diagnostic only; the trace is still emitted.
+     */
+    anomalies: string[];
+}
+export interface HistogramSummary {
+    count: number;
+    p50: number | null;
+    p90: number | null;
+    p99: number | null;
+    min: number | null;
+    max: number | null;
+    mean: number | null;
+}
+/**
+ * Bounded-sample running histogram for one derived metric. Keeps the last
+ * `capacity` samples (FIFO) and computes percentiles on demand. Bounded so
+ * a long-running process does not grow without limit.
+ *
+ * Exported so sibling accumulators (e.g. the Mobile Resource Workbench's
+ * `DeviceResourceMetrics`) reuse the same percentile logic instead of
+ * re-implementing it.
+ */
+export declare class BoundedHistogram {
+    private readonly capacity;
+    private readonly samples;
+    constructor(capacity: number);
+    add(value: number): void;
+    summary(): HistogramSummary;
+}
+export interface TracerOptions {
+    /** Max number of completed traces to retain in the ring. Default 64. */
+    ringCapacity?: number;
+    /** Max samples per derived-metric histogram. Default 256. */
+    histogramCapacity?: number;
+    /**
+     * Max number of concurrently-open turns. A new `beginTurn` past this cap
+     * evicts the oldest still-open turn (it is closed and emitted with whatever
+     * checkpoints it had). Guards against a leaked turn never being closed.
+     * Default 16.
+     */
+    maxOpenTurns?: number;
+}
+export declare class EndToEndLatencyTracer {
+    private readonly ring;
+    private readonly open;
+    private readonly byRoom;
+    private readonly histograms;
+    private readonly ringCapacity;
+    private readonly histogramCapacity;
+    private readonly maxOpenTurns;
+    constructor(opts?: TracerOptions);
+    /**
+     * Open a new turn. Returns the `turnId`. If `roomId` is given, subsequent
+     * context-free marks for that room route to this turn until it is closed.
+     */
+    beginTurn(args?: {
+        turnId?: string;
+        roomId?: string | null;
+    }): string;
+    /** Resolve (or lazily open) a turn for a roomId. Used by the helper. */
+    turnForRoom(roomId: string): string;
+    /**
+     * Record a checkpoint on an open turn. No-op (with a warning) if the turn
+     * is unknown or already closed — a late mark on a finalized turn is a
+     * caller bug, not something to retroactively patch into history.
+     */
+    mark(turnId: string, checkpoint: VoiceCheckpoint, atEpochMs?: number): void;
+    /** Convenience: mark a checkpoint by roomId, opening a turn if needed. */
+    markByRoom(roomId: string, checkpoint: VoiceCheckpoint, atEpochMs?: number): void;
+    /**
+     * Close an open turn: snapshot it into a `LatencyTrace`, push to the ring
+     * (evicting the oldest), and fold its derived metrics into the histograms.
+     * Idempotent for an unknown turnId. Returns the emitted trace (or null if
+     * the turn was unknown).
+     */
+    endTurn(turnId: string): LatencyTrace | null;
+    /** A read-only snapshot of an open turn (does not close it). */
+    peekTurn(turnId: string): LatencyTrace | null;
+    /** The most recent `n` completed traces, newest last. */
+    recentTraces(n?: number): LatencyTrace[];
+    /** Per-derived-metric histogram summaries over the retained sample. */
+    histogramSummaries(): Record<LatencyDerivedKey, HistogramSummary>;
+    /** Drop all retained traces, histograms, and open turns. */
+    reset(): void;
+    /** Number of turns currently open (un-closed). */
+    get openTurnCount(): number;
+    /**
+     * Bridge a VAD event source onto this tracer: subscribes to the
+     * `VadEvent` stream and emits `vad-trigger` + `vad-speech-start` on the
+     * Silero rising edge (the earliest reliable per-turn `t0`). Returns the
+     * unsubscribe function. This is the documented seam that lets the tracer
+     * hook the VAD without editing `voice/vad.ts` — the true energy-rise
+     * "wake" instant is owned by the turn controller (W9), which calls
+     * `mark(turnId, "vad-trigger")` directly; this bridge is the fallback for
+     * plain VAD-only setups.
+     */
+    bindVadDetector(source: VadEventSource, args?: {
+        roomId?: string | null;
+        onTurnOpen?: (turnId: string) => void;
+    }): () => void;
+    private snapshotTurn;
+    private computeDerived;
+}
+/**
+ * Process-wide tracer. The turn controller (W9) owns per-turn lifecycle
+ * via `beginTurn` / `endTurn`; components that only know a `roomId` use
+ * `markVoiceLatency(roomId, checkpoint)` which routes through `markByRoom`.
+ * The dev endpoint (`GET /api/dev/voice-latency`) reads this singleton.
+ */
+export declare const voiceLatencyTracer: EndToEndLatencyTracer;
+/**
+ * Record a checkpoint on the process-wide tracer, keyed by `roomId`. Opens
+ * a turn for that room on first call. No-op-safe — instrumentation must
+ * never throw into the voice loop. This is the seam every component (VAD,
+ * turn controller, engine, field extractor, chunker, TTS backend, audio
+ * sink) can call without threading a tracer reference.
+ */
+export declare function markVoiceLatency(roomId: string | null | undefined, checkpoint: VoiceCheckpoint, atEpochMs?: number): void;
+/** Close the process-wide tracer's turn for a roomId, returning the trace. */
+export declare function endVoiceLatencyTurn(roomId: string): LatencyTrace | null;
+export interface VoiceLatencyDevPayload {
+    generatedAtEpochMs: number;
+    /** Checkpoint names, in canonical order — so consumers can render headers. */
+    checkpoints: ReadonlyArray<VoiceCheckpoint>;
+    derivedKeys: ReadonlyArray<LatencyDerivedKey>;
+    openTurnCount: number;
+    traces: LatencyTrace[];
+    histograms: Record<LatencyDerivedKey, HistogramSummary>;
+}
+/** Build the JSON body for `GET /api/dev/voice-latency`. */
+export declare function buildVoiceLatencyDevPayload(tracer?: EndToEndLatencyTracer, limit?: number): VoiceLatencyDevPayload;
+/** A per-turn observation fed to `VoiceRunMetrics.recordTurn`. Every field is
+ *  optional — a turn that couldn't measure a quantity records it as missing,
+ *  never as a fabricated zero (AGENTS.md §3 / §7). */
+export interface VoiceTurnMetrics {
+    /** MTP drafter token-acceptance rate (n_drafted_accepted / n_drafted)
+     *  for this turn's generation, from the llama-server `/metrics` deltas. */
+    mtpAcceptRate?: number | null;
+    /** Tokens accepted from the drafter this turn (for an aggregate accept-rate
+     *  that weights by token count, not turn count). */
+    mtpAccepted?: number | null;
+    /** Tokens drafted this turn. */
+    mtpDrafted?: number | null;
+    /** Structured-decode token-savings % for this turn — tokens the grammar
+     *  force-filled ÷ tokens that would otherwise have been generated, ×100
+     *  (WS-4's `guided_decode_token_bench.mjs` counter; ≈28% aggregate forced
+     *  on the synthetic action set). */
+    structuredDecodeTokenSavingsPct?: number | null;
+    /** Decode throughput (tokens / second) for this turn's generation. */
+    tokensPerSecond?: number | null;
+    /** Server resident-set high-water mark in MB at the end of this turn
+     *  (`VmHWM` from `/proc/<pid>/status`). */
+    serverRssMb?: number | null;
+}
+export interface VoiceRunMetricsSummary {
+    turns: number;
+    /** MTP accept-rate, token-weighted across the run (Σaccepted / Σdrafted);
+     *  `null` when nothing was drafted / no drafter present. */
+    mtpAcceptRate: number | null;
+    mtpAccepted: number;
+    mtpDrafted: number;
+    /** Per-turn accept-rate histogram (p50/p90/p99 etc. — bounded sample). */
+    mtpAcceptRateHistogram: HistogramSummary;
+    /** Mean / histogram of the structured-decode token-savings %. */
+    structuredDecodeTokenSavingsPct: HistogramSummary;
+    /** Mean / histogram of decode tok/s. */
+    tokensPerSecond: HistogramSummary;
+    /** Server RSS over the run: first / last / max in MB + the `leakSuspected`
+     *  flag (true when RSS is monotone non-decreasing across ≥4 turns and grew
+     *  by more than `leakGrowthMbThreshold`). */
+    rss: {
+        firstMb: number | null;
+        lastMb: number | null;
+        maxMb: number | null;
+        samples: number;
+        leakSuspected: boolean;
+        growthMb: number | null;
+    };
+}
+/**
+ * Accumulates the non-latency signals over a long voice run (the duet harness
+ * feeds it per-turn). Sibling to `EndToEndLatencyTracer` (which is per-turn
+ * spans only). The duet bench report (`voice-duet-bench-<model>.json`) writes
+ * `summary()` next to the latency histograms; `eliza1_gates_collect.mjs`
+ * ingests the gate-named fields.
+ */
+export declare class VoiceRunMetrics {
+    private readonly opts;
+    private turns;
+    private mtpAccepted;
+    private mtpDrafted;
+    private readonly acceptRateHist;
+    private readonly savingsHist;
+    private readonly tokSecHist;
+    private readonly rssSamples;
+    constructor(opts?: {
+        leakGrowthMbThreshold?: number;
+    });
+    recordTurn(m: VoiceTurnMetrics): void;
+    summary(): VoiceRunMetricsSummary;
+    reset(): void;
+}
+//# sourceMappingURL=latency-trace.d.ts.map

package/src/services/latency-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency-trace.d.ts","sourceRoot":"","sources":["latency-trace.ts"],"names":[],"mappings":"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"}

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);
+	});
+});