@kuralle-syrinx/core 4.4.0 → 4.5.0

package/src/iu-ledger.test.ts

@@ -0,0 +1,276 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+import type { IncrementalUnit, IncrementalUnitId } from "./incremental-unit.js";
+import { InMemoryIuLedger, type IuLedgerAnomaly } from "./iu-ledger.js";
+
+function makeId(contextId: string, iuId: string, epoch = 1): IncrementalUnitId {
+  return { contextId, iuId, epoch };
+}
+
+function makeIu(
+  contextId: string,
+  iuId: string,
+  kind: IncrementalUnit["kind"],
+  epoch = 1,
+): IncrementalUnit {
+  return {
+    id: makeId(contextId, iuId, epoch),
+    kind,
+    state: "hypothesized",
+  };
+}
+
+function seedContexts(ledger: InMemoryIuLedger, count: number): IncrementalUnitId {
+  const target = makeId("ctx-target", "iu-target");
+  for (let i = 0; i < count; i++) {
+    ledger.add(makeIu(`ctx-${i}`, `iu-${i}`, "user_turn", i));
+  }
+  ledger.add(makeIu(target.contextId, target.iuId, "user_turn", target.epoch));
+  return target;
+}
+
+describe("InMemoryIuLedger", () => {
+  describe("add", () => {
+    it("registers a hypothesized IU (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      expect(ledger.get(iu.id)?.state).toBe("hypothesized");
+    });
+
+    it("overwrites an existing iuId with the latest add (failure path: stale hypothesis replaced)", () => {
+      const ledger = new InMemoryIuLedger();
+      const first = makeIu("ctx-a", "iu-1", "user_turn", 1);
+      const second = makeIu("ctx-a", "iu-1", "assistant_response", 2);
+      ledger.add(first);
+      ledger.add(second);
+      expect(ledger.get(first.id)?.kind).toBe("assistant_response");
+      expect(ledger.get(first.id)?.id.epoch).toBe(2);
+    });
+  });
+
+  describe("commit", () => {
+    it("transitions hypothesized → committed (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const iu = makeIu("ctx-a", "iu-1", "assistant_response");
+      ledger.add(iu);
+      ledger.commit(iu.id);
+      expect(ledger.get(iu.id)?.state).toBe("committed");
+    });
+
+    it("records committedPrefix when provided (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const iu = makeIu("ctx-a", "iu-1", "tts_segment");
+      ledger.add(iu);
+      ledger.commit(iu.id, { ms: 800, chars: 40 });
+      expect(ledger.get(iu.id)?.committedPrefix).toEqual({ ms: 800, chars: 40 });
+    });
+
+    it("is a no-op on an already-committed IU and fires terminal_op (failure path)", () => {
+      const onEvent = vi.fn<(a: IuLedgerAnomaly) => void>();
+      const ledger = new InMemoryIuLedger(onEvent);
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      ledger.commit(iu.id);
+      ledger.commit(iu.id);
+      expect(ledger.get(iu.id)?.state).toBe("committed");
+      expect(onEvent).toHaveBeenCalledOnce();
+      expect(onEvent).toHaveBeenCalledWith({
+        kind: "terminal_op",
+        op: "commit",
+        id: iu.id,
+        state: "committed",
+      });
+    });
+
+    it("does not un-commit: revoke after commit is a no-op with terminal_op (failure path)", () => {
+      const onEvent = vi.fn<(a: IuLedgerAnomaly) => void>();
+      const ledger = new InMemoryIuLedger(onEvent);
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      ledger.commit(iu.id);
+      ledger.revoke(iu.id);
+      expect(ledger.get(iu.id)?.state).toBe("committed");
+      expect(onEvent).toHaveBeenCalledOnce();
+      expect(onEvent).toHaveBeenCalledWith({
+        kind: "terminal_op",
+        op: "revoke",
+        id: iu.id,
+        state: "committed",
+      });
+    });
+
+    it("fail-open on unknown iuId: no throw, unknown_iu anomaly (failure path)", () => {
+      const onEvent = vi.fn<(a: IuLedgerAnomaly) => void>();
+      const ledger = new InMemoryIuLedger(onEvent);
+      const id = makeId("missing", "iu-1");
+      expect(() => ledger.commit(id)).not.toThrow();
+      expect(onEvent).toHaveBeenCalledWith({ kind: "unknown_iu", op: "commit", id });
+    });
+  });
+
+  describe("revoke", () => {
+    it("transitions hypothesized → revoked (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      ledger.revoke(iu.id);
+      expect(ledger.get(iu.id)?.state).toBe("revoked");
+    });
+
+    it("is a no-op on an already-revoked IU and fires terminal_op (failure path)", () => {
+      const onEvent = vi.fn<(a: IuLedgerAnomaly) => void>();
+      const ledger = new InMemoryIuLedger(onEvent);
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      ledger.revoke(iu.id);
+      ledger.revoke(iu.id);
+      expect(ledger.get(iu.id)?.state).toBe("revoked");
+      expect(onEvent).toHaveBeenCalledOnce();
+      expect(onEvent).toHaveBeenCalledWith({
+        kind: "terminal_op",
+        op: "revoke",
+        id: iu.id,
+        state: "revoked",
+      });
+    });
+
+    it("fail-open on unknown iuId: no throw, unknown_iu anomaly (failure path)", () => {
+      const onEvent = vi.fn<(a: IuLedgerAnomaly) => void>();
+      const ledger = new InMemoryIuLedger(onEvent);
+      const id = makeId("missing", "iu-1");
+      expect(() => ledger.revoke(id)).not.toThrow();
+      expect(onEvent).toHaveBeenCalledWith({ kind: "unknown_iu", op: "revoke", id });
+    });
+  });
+
+  describe("get", () => {
+    it("returns the registered IU (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const iu = makeIu("ctx-a", "iu-1", "user_turn");
+      ledger.add(iu);
+      expect(ledger.get(iu.id)).toBe(iu);
+    });
+
+    it("returns undefined for an unknown id without throwing (failure path)", () => {
+      const ledger = new InMemoryIuLedger();
+      expect(ledger.get(makeId("missing", "iu-1"))).toBeUndefined();
+    });
+  });
+
+  describe("latest", () => {
+    it("returns the most recently added IU of the requested kind (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      ledger.add(makeIu("ctx-a", "iu-1", "user_turn"));
+      ledger.add(makeIu("ctx-a", "iu-2", "assistant_response"));
+      ledger.add(makeIu("ctx-a", "iu-3", "user_turn"));
+      const latest = ledger.latest("ctx-a", "user_turn");
+      expect(latest?.id.iuId).toBe("iu-3");
+    });
+
+    it("returns undefined when no IU of that kind exists (failure path)", () => {
+      const ledger = new InMemoryIuLedger();
+      ledger.add(makeIu("ctx-a", "iu-1", "user_turn"));
+      expect(ledger.latest("ctx-a", "tts_segment")).toBeUndefined();
+      expect(ledger.latest("missing", "user_turn")).toBeUndefined();
+    });
+  });
+
+  describe("clear", () => {
+    it("removes only the requested context (happy path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const a = makeIu("ctx-a", "iu-1", "user_turn");
+      const b = makeIu("ctx-b", "iu-1", "user_turn");
+      ledger.add(a);
+      ledger.add(b);
+      ledger.clear("ctx-a");
+      expect(ledger.get(a.id)).toBeUndefined();
+      expect(ledger.get(b.id)?.state).toBe("hypothesized");
+    });
+
+    it("is a no-op for an unknown context without affecting others (failure path)", () => {
+      const ledger = new InMemoryIuLedger();
+      const b = makeIu("ctx-b", "iu-1", "user_turn");
+      ledger.add(b);
+      ledger.clear("ctx-missing");
+      expect(ledger.get(b.id)?.state).toBe("hypothesized");
+    });
+  });
+
+  describe("monotonic state machine", () => {
+    it("follows hypothesized → committed and hypothesized → revoked only", () => {
+      const ledger = new InMemoryIuLedger();
+      const committed = makeIu("ctx-a", "iu-commit", "user_turn");
+      const revoked = makeIu("ctx-a", "iu-revoke", "user_turn");
+      ledger.add(committed);
+      ledger.add(revoked);
+      ledger.commit(committed.id);
+      ledger.revoke(revoked.id);
+      expect(ledger.get(committed.id)?.state).toBe("committed");
+      expect(ledger.get(revoked.id)?.state).toBe("revoked");
+    });
+  });
+
+  describe("maxContexts bound", () => {
+    it("evicts the oldest context when a new context exceeds the cap (FIFO)", () => {
+      const ledger = new InMemoryIuLedger(() => {}, 3);
+      const a = makeIu("a", "iu-1", "user_turn");
+      const b = makeIu("b", "iu-1", "user_turn");
+      const c = makeIu("c", "iu-1", "user_turn");
+      const d = makeIu("d", "iu-1", "user_turn");
+      ledger.add(a);
+      ledger.add(b);
+      ledger.add(c);
+      ledger.add(d);
+      expect(ledger.get(a.id)).toBeUndefined();
+      expect(ledger.get(b.id)?.state).toBe("hypothesized");
+      expect(ledger.get(c.id)?.state).toBe("hypothesized");
+      expect(ledger.get(d.id)?.state).toBe("hypothesized");
+    });
+
+    it("does not evict when adding another IU to an existing context", () => {
+      const ledger = new InMemoryIuLedger(() => {}, 3);
+      const a1 = makeIu("a", "iu-1", "user_turn");
+      const a2 = makeIu("a", "iu-2", "assistant_response");
+      const b = makeIu("b", "iu-1", "user_turn");
+      const c = makeIu("c", "iu-1", "user_turn");
+      ledger.add(a1);
+      ledger.add(b);
+      ledger.add(c);
+      ledger.add(a2);
+      expect(ledger.get(a1.id)?.state).toBe("hypothesized");
+      expect(ledger.get(a2.id)?.state).toBe("hypothesized");
+      expect(ledger.get(b.id)?.state).toBe("hypothesized");
+      expect(ledger.get(c.id)?.state).toBe("hypothesized");
+    });
+  });
+
+  describe("O(1) per-op (structural)", () => {
+    it("commit/get touch only the target ctx bucket regardless of total ctx count", () => {
+      // Map.get/set/delete are O(1); each hot-path op does at most one outer + one inner lookup.
+      const ledgerSmall = new InMemoryIuLedger();
+      const ledgerLarge = new InMemoryIuLedger();
+      const targetSmall = seedContexts(ledgerSmall, 10);
+      const targetLarge = seedContexts(ledgerLarge, 1000);
+
+      ledgerSmall.commit(targetSmall);
+      ledgerLarge.commit(targetLarge);
+
+      expect(ledgerSmall.get(targetSmall)?.state).toBe("committed");
+      expect(ledgerLarge.get(targetLarge)?.state).toBe("committed");
+
+      const timeOp = (ledger: InMemoryIuLedger, id: IncrementalUnitId) => {
+        const start = performance.now();
+        for (let i = 0; i < 5000; i++) {
+          ledger.get(id);
+        }
+        return performance.now() - start;
+      };
+
+      const tSmall = timeOp(ledgerSmall, targetSmall);
+      const tLarge = timeOp(ledgerLarge, targetLarge);
+      expect(tLarge).toBeLessThan(Math.max(tSmall * 20, 1));
+    });
+  });
+});

package/src/latency-filler.test.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  LatencyFillerController,
+  selectLatencyFillerConnective,
+  stripRedundantFillerPrefix,
+} from "./latency-filler.js";
+import { LATENCY_FILLER_FIXTURES } from "./latency-filler-fixtures.js";
+
+describe("selectLatencyFillerConnective", () => {
+  it("selects question and gratitude connectives from fixtures", () => {
+    for (const fixture of LATENCY_FILLER_FIXTURES) {
+      const turnIndex = fixture.id === "statement-1" ? 1 : 0;
+      expect(selectLatencyFillerConnective(fixture.userText, turnIndex)).toBe(fixture.expectedConnective);
+    }
+  });
+});
+
+describe("stripRedundantFillerPrefix", () => {
+  it("removes a duplicated leading connective without leaving a gap", () => {
+    expect(stripRedundantFillerPrefix("So,", "So here's the answer.")).toBe("here's the answer.");
+    expect(stripRedundantFillerPrefix("Well,", "  Well, the deadline passed.")).toBe("the deadline passed.");
+  });
+
+  it("preserves unrelated LLM text", () => {
+    expect(stripRedundantFillerPrefix("So,", "The deadline passed.")).toBe("The deadline passed.");
+  });
+
+  it("does not strip filler words embedded in longer words", () => {
+    expect(stripRedundantFillerPrefix("So,", "Some people say...")).toBe("Some people say...");
+    expect(stripRedundantFillerPrefix("So,", "Social distancing matters")).toBe("Social distancing matters");
+    expect(stripRedundantFillerPrefix("Well,", "Wellness is important")).toBe("Wellness is important");
+    expect(stripRedundantFillerPrefix("Well,", "Welcome back")).toBe("Welcome back");
+    expect(stripRedundantFillerPrefix("Well,", "Wellington is windy")).toBe("Wellington is windy");
+  });
+
+  it("still strips a genuine repeated filler connective", () => {
+    expect(stripRedundantFillerPrefix("So,", "So, the plan is simple.")).toBe("the plan is simple.");
+    expect(stripRedundantFillerPrefix("Well,", "Well, let me explain.")).toBe("let me explain.");
+  });
+});
+
+describe("LatencyFillerController", () => {
+  it("tracks active filler-only state until splice or cancel", () => {
+    const controller = new LatencyFillerController({ enabled: true });
+    expect(controller.start("turn-1", "hello")).toBe("So,");
+    expect(controller.isFillerOnly("turn-1")).toBe(true);
+    expect(controller.spliceLlmDelta("turn-1", "The answer is ready.")).toBe("The answer is ready.");
+    expect(controller.isFillerOnly("turn-1")).toBe(false);
+    expect(controller.getState("turn-1")?.spliced).toBe(true);
+  });
+
+  it("marks filler cancelled without splicing", () => {
+    const controller = new LatencyFillerController({ enabled: true });
+    controller.start("turn-1", "hello");
+    const cancelled = controller.cancel("turn-1");
+    expect(cancelled?.text).toBe("So,");
+    expect(controller.isFillerOnly("turn-1")).toBe(false);
+    expect(controller.spliceLlmDelta("turn-1", "ignored")).toBe("ignored");
+  });
+});

package/src/observability-observer.test.ts

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { PipelineBusImpl, Route } from "./pipeline-bus.js";
+import { InMemoryMetricsExporter } from "./observability.js";
+import { ObservabilityObserver } from "./observability-observer.js";
+import type {
+  TurnBoundaryEventPacket,
+  VadSpeechStartedPacket,
+  VadSpeechEndedPacket,
+  EndOfSpeechPacket,
+  TextToSpeechAudioPacket,
+  TextToSpeechEndPacket,
+  InterruptionDetectedPacket,
+} from "./packets.js";
+
+async function drainBus(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+async function withObserver(
+  fn: (ctx: {
+    bus: PipelineBusImpl;
+    exporter: InMemoryMetricsExporter;
+    boundaries: TurnBoundaryEventPacket[];
+  }) => void | Promise<void>,
+): Promise<void> {
+  const bus = new PipelineBusImpl();
+  const exporter = new InMemoryMetricsExporter();
+  const boundaries: TurnBoundaryEventPacket[] = [];
+  bus.on("obs.turn_boundary", (pkt) => {
+    boundaries.push(pkt as TurnBoundaryEventPacket);
+  });
+
+  const observer = new ObservabilityObserver({
+    bus,
+    exporter,
+    sessionId: "sess-1",
+    dims: { provider: "p1", model: "m1", region: "r1" },
+    getContextId: () => "",
+  });
+  observer.wire();
+
+  const startP = bus.start();
+  await new Promise((r) => setTimeout(r, 5));
+  await fn({ bus, exporter, boundaries });
+  await drainBus();
+  bus.stop();
+  await startP;
+  observer.dispose();
+}
+
+const SPEECH_ID = "turn-abc";
+
+describe("ObservabilityObserver", () => {
+  it("emits turn boundaries and v2v_ms histogram for a full turn", async () => {
+    await withObserver(async ({ bus, exporter, boundaries }) => {
+      bus.push(Route.Main, {
+        kind: "vad.speech_started",
+        contextId: SPEECH_ID,
+        timestampMs: 1000,
+        confidence: 0.9,
+      } satisfies VadSpeechStartedPacket);
+
+      bus.push(Route.Main, {
+        kind: "vad.speech_ended",
+        contextId: SPEECH_ID,
+        timestampMs: 1100,
+      } satisfies VadSpeechEndedPacket);
+
+      bus.push(Route.Main, {
+        kind: "eos.turn_complete",
+        contextId: SPEECH_ID,
+        timestampMs: 1200,
+        text: "hello",
+        transcripts: [],
+      } satisfies EndOfSpeechPacket);
+
+      bus.push(Route.Main, {
+        kind: "tts.audio",
+        contextId: SPEECH_ID,
+        timestampMs: 1300,
+        audio: new Uint8Array(320),
+        sampleRateHz: 16000,
+      } satisfies TextToSpeechAudioPacket);
+
+      bus.push(Route.Main, {
+        kind: "tts.audio",
+        contextId: SPEECH_ID,
+        timestampMs: 1400,
+        audio: new Uint8Array(320),
+        sampleRateHz: 16000,
+      } satisfies TextToSpeechAudioPacket);
+
+      bus.push(Route.Main, {
+        kind: "tts.end",
+        contextId: SPEECH_ID,
+        timestampMs: 1500,
+      } satisfies TextToSpeechEndPacket);
+      await drainBus();
+
+      const kinds = boundaries.map((b) => b.boundary);
+      expect(kinds).toEqual([
+        "user_started_speaking",
+        "user_stopped_speaking",
+        "agent_thinking",
+        "agent_started_speaking",
+        "agent_audio_done",
+      ]);
+
+      for (const b of boundaries) {
+        expect(b.kind).toBe("obs.turn_boundary");
+        expect(b.sessionId).toBe("sess-1");
+        expect(b.speechId).toBe(SPEECH_ID);
+        expect(b.provider).toBe("p1");
+        expect(b.model).toBe("m1");
+        expect(b.region).toBe("r1");
+        expect(b.monotonicMs).toBeGreaterThan(0);
+        expect(b.cancelled).toBeUndefined();
+      }
+
+      const v2v = exporter.histograms.find((h) => h.name === "v2v_ms");
+      expect(v2v).toBeDefined();
+      expect(v2v!.valueMs).toBeGreaterThanOrEqual(0);
+      expect(v2v!.tags).toEqual({
+        provider: "p1",
+        model: "m1",
+        region: "r1",
+        cancelled: "false",
+        layer: "conversation",
+      });
+
+      const thinking = exporter.histograms.find((h) => h.name === "thinking_ms");
+      expect(thinking).toBeDefined();
+      expect(thinking!.valueMs).toBeGreaterThanOrEqual(0);
+
+      const agentSpeech = exporter.histograms.find((h) => h.name === "agent_speech_ms");
+      expect(agentSpeech).toBeDefined();
+      expect(agentSpeech!.valueMs).toBeGreaterThanOrEqual(0);
+
+      for (const histogram of exporter.histograms) {
+        expect(histogram.tags).not.toHaveProperty("sessionId");
+        expect(histogram.tags).not.toHaveProperty("speechId");
+      }
+    });
+  });
+
+  it("tags interruption boundary and histograms as cancelled", async () => {
+    await withObserver(async ({ bus, exporter, boundaries }) => {
+      bus.push(Route.Critical, {
+        kind: "interrupt.detected",
+        contextId: SPEECH_ID,
+        timestampMs: 2000,
+        source: "vad",
+      } satisfies InterruptionDetectedPacket);
+      await drainBus();
+
+      const interruption = boundaries.find((b) => b.boundary === "interruption");
+      expect(interruption).toBeDefined();
+      expect(interruption!.cancelled).toBe(true);
+
+      const withCancelled = exporter.histograms.filter((h) => h.tags.cancelled === "true");
+      for (const h of withCancelled) {
+        expect(h.tags).toMatchObject({
+          sessionId: "sess-1",
+          speechId: SPEECH_ID,
+          cancelled: "true",
+        });
+      }
+    });
+  });
+
+  it("emits agent_started_speaking only once per speechId", async () => {
+    await withObserver(async ({ bus, boundaries }) => {
+      bus.push(Route.Main, {
+        kind: "tts.audio",
+        contextId: SPEECH_ID,
+        timestampMs: 100,
+        audio: new Uint8Array(4),
+        sampleRateHz: 16000,
+      } satisfies TextToSpeechAudioPacket);
+      bus.push(Route.Main, {
+        kind: "tts.audio",
+        contextId: SPEECH_ID,
+        timestampMs: 200,
+        audio: new Uint8Array(4),
+        sampleRateHz: 16000,
+      } satisfies TextToSpeechAudioPacket);
+      await drainBus();
+
+      const started = boundaries.filter((b) => b.boundary === "agent_started_speaking");
+      expect(started).toHaveLength(1);
+    });
+  });
+
+  it("uses provider/model/region dimensions from STT and TTS packets when present", async () => {
+    await withObserver(async ({ bus, exporter, boundaries }) => {
+      bus.push(Route.Main, {
+        kind: "vad.speech_ended",
+        contextId: SPEECH_ID,
+        timestampMs: 1100,
+      } satisfies VadSpeechEndedPacket);
+      bus.push(Route.Main, {
+        kind: "eos.turn_complete",
+        contextId: SPEECH_ID,
+        timestampMs: 1200,
+        text: "hello",
+        transcripts: [
+          {
+            kind: "stt.result",
+            contextId: SPEECH_ID,
+            timestampMs: 1190,
+            text: "hello",
+            confidence: 0.9,
+            provider: { name: "deepgram", model: "nova-3", region: "global" },
+          },
+        ],
+      } satisfies EndOfSpeechPacket);
+      bus.push(Route.Main, {
+        kind: "tts.audio",
+        contextId: SPEECH_ID,
+        timestampMs: 1300,
+        audio: new Uint8Array(320),
+        sampleRateHz: 16000,
+        provider: { name: "cartesia", model: "sonic-3", region: "global", cancelled: false },
+      } satisfies TextToSpeechAudioPacket);
+      await drainBus();
+
+      const started = boundaries.find((b) => b.boundary === "agent_started_speaking");
+      expect(started).toMatchObject({
+        provider: "cartesia",
+        model: "sonic-3",
+        region: "global",
+      });
+      const thinking = boundaries.find((b) => b.boundary === "agent_thinking");
+      expect(thinking).toMatchObject({
+        provider: "deepgram",
+        model: "nova-3",
+        region: "global",
+      });
+      expect(exporter.histograms.find((h) => h.name === "v2v_ms")?.tags).toMatchObject({
+        provider: "cartesia",
+        model: "sonic-3",
+        region: "global",
+      });
+    });
+  });
+});

package/src/observability.test.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  InMemoryMetricsExporter,
+  localizeTurn,
+  monotonicNowMs,
+  noopMetricsExporter,
+  reconstructTurnTimeline,
+} from "./observability.js";
+import type { TurnBoundaryEventPacket } from "./packets.js";
+
+describe("monotonicNowMs", () => {
+  it("returns increasing positive numbers", () => {
+    const first = monotonicNowMs();
+    const second = monotonicNowMs();
+    expect(first).toBeGreaterThan(0);
+    expect(second).toBeGreaterThanOrEqual(first);
+  });
+});
+
+describe("InMemoryMetricsExporter", () => {
+  it("records histogram name, value, and tags", () => {
+    const exporter = new InMemoryMetricsExporter();
+    exporter.observeHistogram("turn.latency_ms", 42, { sessionId: "s1", boundary: "agent_audio_done" });
+    expect(exporter.histograms).toEqual([
+      {
+        name: "turn.latency_ms",
+        valueMs: 42,
+        tags: { sessionId: "s1", boundary: "agent_audio_done" },
+      },
+    ]);
+  });
+
+  it("records non-negative span duration on end", () => {
+    vi.useFakeTimers();
+    const exporter = new InMemoryMetricsExporter();
+    const handle = exporter.startSpan("turn.process", { sessionId: "s1" });
+    vi.advanceTimersByTime(10);
+    handle.end();
+    expect(exporter.spans).toHaveLength(1);
+    expect(exporter.spans[0]?.durationMs).toBeGreaterThanOrEqual(0);
+    vi.useRealTimers();
+  });
+});
+
+describe("noopMetricsExporter", () => {
+  it("accepts histogram and span calls without throwing", () => {
+    noopMetricsExporter.observeHistogram("ignored", 0, {});
+    noopMetricsExporter.startSpan("ignored", {}).end();
+  });
+});
+
+describe("turn localization", () => {
+  it("prioritizes infrastructure, keeps conversation-only failures separate, and reports clean turns", () => {
+    expect(localizeTurn({ infrastructureBreached: true, conversationFlagged: true })).toBe("infrastructure");
+    expect(localizeTurn({ infrastructureBreached: false, conversationFlagged: true })).toBe("conversation");
+    expect(localizeTurn({ infrastructureBreached: false, conversationFlagged: false })).toBe("none");
+  });
+});
+
+describe("reconstructTurnTimeline", () => {
+  function ev(sessionId: string, speechId: string, boundary: TurnBoundaryEventPacket["boundary"], monotonicMs: number, cancelled = false): TurnBoundaryEventPacket {
+    return { kind: "obs.turn_boundary", contextId: speechId, timestampMs: 0, boundary, sessionId, speechId, monotonicMs, cancelled };
+  }
+
+  it("orders one session's boundaries by monotonic time with inter-boundary deltas", () => {
+    const events = [
+      ev("sess-A", "turn-1", "agent_started_speaking", 300),
+      ev("sess-A", "turn-1", "user_started_speaking", 100),
+      ev("sess-B", "turn-9", "user_started_speaking", 150), // other session — excluded
+      ev("sess-A", "turn-1", "user_stopped_speaking", 200),
+    ];
+    const timeline = reconstructTurnTimeline(events, "sess-A");
+    expect(timeline.map((s) => s.boundary)).toEqual([
+      "user_started_speaking",
+      "user_stopped_speaking",
+      "agent_started_speaking",
+    ]);
+    expect(timeline.map((s) => s.sincePrevMs)).toEqual([0, 100, 100]);
+    expect(timeline.every((s) => s.speechId === "turn-1")).toBe(true);
+  });
+
+  it("filters by speechId when provided and surfaces the cancelled flag", () => {
+    const events = [
+      ev("s", "t1", "user_started_speaking", 10),
+      ev("s", "t2", "interruption", 20, true),
+    ];
+    const t2 = reconstructTurnTimeline(events, "s", "t2");
+    expect(t2).toHaveLength(1);
+    expect(t2[0]!.cancelled).toBe(true);
+  });
+});