@urun-sh/sense 0.0.0-stage → 0.1.0

package/dist/wave.js

@@ -0,0 +1,209 @@
+import { ProtocolError } from "./errors.js";
+/** One question's answer in a wave. */
+export class Result {
+    id;
+    kind;
+    waveId;
+    /** noul: boolean; choice: top option name; score: expected ordinal Σi·p. */
+    value;
+    /** noul: P(true); choice: P(top); score: P(top level). */
+    p;
+    confidence;
+    /** Label-keyed probabilities (score: level names). */
+    distribution;
+    /** argmax label ("true"/"false" for noul, option name, level name). */
+    top;
+    constructor(init) {
+        this.id = init.id;
+        this.kind = init.kind;
+        this.waveId = init.waveId;
+        this.value = init.value;
+        this.p = init.p;
+        this.confidence = init.confidence;
+        this.distribution = init.distribution;
+        this.top = init.top;
+    }
+    pOption(name) {
+        if (this.kind === "score") {
+            throw new ProtocolError("protocol", `pOption(${name}) on score question ${this.id}`);
+        }
+        return this.distribution[name] ?? 0;
+    }
+    /** Only valid on score results: Σ p over levels >= the given level. */
+    pAtLeast(level) {
+        throw new ProtocolError("protocol", `pAtLeast(${level}) on non-score question ${this.id}`);
+    }
+}
+/** Score result: ordinal distribution over ordered levels. */
+export class Score extends Result {
+    levels;
+    /** argmax level name. */
+    level;
+    constructor(init) {
+        const byName = {};
+        let expected = 0;
+        let bestIdx = 0;
+        init.levels.forEach((name, i) => {
+            const p = init.probs[String(i)] ?? 0;
+            byName[name] = p;
+            expected += i * p;
+            if (p > (init.probs[String(bestIdx)] ?? 0))
+                bestIdx = i;
+        });
+        const level = init.levels[bestIdx] ?? "";
+        super({
+            id: init.id,
+            kind: "score",
+            waveId: init.waveId,
+            value: expected,
+            p: byName[level] ?? 0,
+            confidence: init.confidence,
+            distribution: byName,
+            top: level,
+        });
+        this.levels = init.levels;
+        this.level = level;
+    }
+    pAtLeast(level) {
+        const idx = this.levels.indexOf(level);
+        if (idx < 0) {
+            throw new ProtocolError("protocol", `unknown level "${level}" for ${this.id}`);
+        }
+        let sum = 0;
+        for (let i = idx; i < this.levels.length; i++) {
+            sum += this.distribution[this.levels[i]] ?? 0;
+        }
+        return sum;
+    }
+}
+const noulTop = (choice) => (choice ? "true" : "false");
+/** One wave: exactly one answer per registered question (§6). */
+export class Wave {
+    waveId;
+    tMs;
+    results;
+    constructor(waveId, tMs, results) {
+        this.waveId = waveId;
+        this.tMs = tMs;
+        this.results = results;
+    }
+    result(qid) {
+        const r = this.results[qid];
+        if (!r) {
+            throw new ProtocolError("unknown_question", `no result for question "${qid}"`);
+        }
+        return r;
+    }
+    has(qid) {
+        return qid in this.results;
+    }
+    questionIds() {
+        return Object.keys(this.results);
+    }
+    /** Decode one wire payload ({wave_id, t_ms, results}) against registered questions. */
+    static decode(questions, payload) {
+        if (typeof payload !== "object" || payload === null) {
+            throw new ProtocolError("protocol", "wave payload must be an object");
+        }
+        const raw = payload;
+        if (typeof raw.results !== "object" || raw.results === null) {
+            throw new ProtocolError("protocol", "wave payload is missing results");
+        }
+        const incoming = raw.results;
+        const results = {};
+        for (const q of questions) {
+            const ans = incoming[q.id];
+            if (ans === undefined) {
+                throw new ProtocolError("missing_answer", `wave has no answer for registered question "${q.id}"`);
+            }
+            results[q.id] = decodeResult(q, ans, numOr(raw.wave_id, 0));
+        }
+        for (const qid of Object.keys(incoming)) {
+            if (!questions.some((q) => q.id === qid)) {
+                throw new ProtocolError("unknown_question", `wave carries unknown question "${qid}"`);
+            }
+        }
+        return new Wave(numOr(raw.wave_id, 0), numOr(raw.t_ms, 0), results);
+    }
+}
+function numOr(v, fallback) {
+    return typeof v === "number" ? v : fallback;
+}
+function decodeAnswerEnvelope(q, ans) {
+    if (typeof ans !== "object" || ans === null) {
+        throw new ProtocolError("protocol", `answer for "${q.id}" must be an object`);
+    }
+    const a = ans;
+    const probs = (typeof a.probabilities === "object" && a.probabilities !== null
+        ? a.probabilities
+        : {});
+    const confidence = typeof a.confidence === "number" ? a.confidence : 0;
+    return { a, probs, confidence };
+}
+function decodeNoulResult(q, a, probs, confidence, waveId) {
+    let choice;
+    if (typeof a.choice === "boolean") {
+        choice = a.choice;
+    }
+    else if (a.choice === "true" || a.choice === "false") {
+        choice = a.choice === "true";
+    }
+    else {
+        throw new ProtocolError("protocol", `noul answer for "${q.id}" has bad choice ${JSON.stringify(a.choice)}`);
+    }
+    const pTrue = probs["true"] ?? (choice ? 1 : 0);
+    return new Result({
+        id: q.id,
+        kind: "noul",
+        waveId,
+        value: choice,
+        p: pTrue,
+        confidence,
+        distribution: probs,
+        top: noulTop(choice),
+    });
+}
+function decodeChoiceResult(q, a, probs, confidence, waveId) {
+    const top = typeof a.choice === "string" ? a.choice : argmax(probs);
+    if (top === undefined) {
+        throw new ProtocolError("protocol", `choice answer for "${q.id}" has no choice`);
+    }
+    return new Result({
+        id: q.id,
+        kind: "choice",
+        waveId,
+        value: top,
+        p: probs[top] ?? 0,
+        confidence,
+        distribution: probs,
+        top,
+    });
+}
+function decodeResult(q, ans, waveId) {
+    const { a, probs, confidence } = decodeAnswerEnvelope(q, ans);
+    if (q.kind === "noul") {
+        return decodeNoulResult(q, a, probs, confidence, waveId);
+    }
+    if (q.kind === "choice") {
+        return decodeChoiceResult(q, a, probs, confidence, waveId);
+    }
+    // score
+    if (!q.levels?.length) {
+        throw new ProtocolError("bad_question", `score question "${q.id}" has no levels`);
+    }
+    return new Score({
+        id: q.id,
+        waveId,
+        probs,
+        levels: q.levels,
+        confidence,
+    });
+}
+function argmax(probs) {
+    let best;
+    for (const [k, v] of Object.entries(probs)) {
+        if (best === undefined || v > (probs[best] ?? -Infinity))
+            best = k;
+    }
+    return best;
+}

package/examples/cheese_demo.html

@@ -0,0 +1,290 @@
+<!doctype html>
+<!-- 🧀 Sense SDK cheese classifier — served by examples/typescript/cheese_demo.ts -->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>🧀 cheese demo</title>
+<style>
+  :root {
+    color-scheme: dark;
+    --green: #3fb950; --yellow: #d29922; --red: #f85149;
+    --grey: #656d76; --magenta: #db61a2; --cyan: #76e3ea; --dim: #8b949e;
+  }
+  * { box-sizing: border-box; margin: 0; }
+  body {
+    background: #0d1117; color: #e6edf3;
+    font-family: -apple-system, system-ui, "Segoe UI", Roboto, sans-serif;
+    min-height: 100dvh; display: flex; flex-direction: column;
+    padding: max(16px, env(safe-area-inset-top)) 16px max(16px, env(safe-area-inset-bottom));
+  }
+  header { display: flex; flex-direction: column; gap: 10px; }
+  #pill { font-size: 14px; }
+  #pill.online { color: var(--green); }
+  #pill.connecting, #pill.waiting, #pill.stalled { color: var(--yellow); }
+  #pill.error { color: var(--red); }
+  #pill.mic-only, #pill.stopped { color: var(--grey); }
+  #meter { display: flex; gap: 2px; align-items: flex-end; height: 28px; }
+  #meter i { flex: 1; background: var(--grey); min-height: 2px; border-radius: 1px; }
+  #speech { font-size: 14px; color: var(--dim); }
+  main { flex: 1; display: flex; align-items: center; justify-content: center; text-align: center; }
+  #verdict { font-size: 20px; color: var(--dim); max-width: 28em; }
+  #verdict.love, #verdict.like { color: var(--green); }
+  #verdict.hate, #verdict.dislike { color: var(--red); }
+  #verdict.meh { color: var(--yellow); }
+  #verdict.love .big, #verdict.like .big, #verdict.hate .big, #verdict.dislike .big, #verdict.meh .big { color: var(--magenta); }
+  #verdict .kind { color: var(--cyan); font-weight: 700; }
+  #verdict .big { font-size: 30px; font-weight: 700; }
+  #verdict .detail { margin-top: 8px; font-size: 20px; }
+  footer { display: flex; flex-direction: column; gap: 10px; }
+  #stats { font-size: 12px; color: var(--grey); font-family: ui-monospace, monospace; text-align: center; min-height: 1em; }
+  #toggle {
+    min-height: 64px; font-size: 20px; font-weight: 600; border: 0; border-radius: 14px;
+    background: #21262d; color: #e6edf3; touch-action: manipulation;
+  }
+  #toggle:disabled { opacity: 0.5; }
+  #toggle.streaming { background: #da3633; }
+</style>
+</head>
+<body>
+  <header>
+    <div id="pill" class="connecting">● connecting</div>
+    <div id="meter"></div>
+    <div id="speech">speech unknown</div>
+  </header>
+  <main><div id="verdict">listening…</div></main>
+  <footer>
+    <div id="stats"></div>
+    <button id="toggle">Start</button>
+  </footer>
+<script>
+"use strict";
+
+const pill = document.getElementById("pill");
+const meterEl = document.getElementById("meter");
+const speechEl = document.getElementById("speech");
+const verdictEl = document.getElementById("verdict");
+const statsEl = document.getElementById("stats");
+const toggle = document.getElementById("toggle");
+
+// -- status and meter ---------------------------------------------------------
+
+const STATES = {
+  connecting: "● connecting",
+  waiting: "● connected · waiting for Sense",
+  stalled: "● connected, but Sense is not responding",
+  online: "● Sense online",
+  "mic-only": "○ sense disabled (mic test)",
+  stopped: "○ stopped",
+  error: "● demo stopped",
+};
+
+function setStatus(name) {
+  pill.className = name;
+  pill.textContent = STATES[name] ?? name;
+}
+
+// "waiting" becomes "stalled" after a sustained silence; the timer arms below.
+const STALL_MS = 15000;
+let stallTimer = null;
+let micStreaming = false;
+let helloSeen = false;
+function disarmStall() {
+  if (stallTimer !== null) {
+    clearTimeout(stallTimer);
+    stallTimer = null;
+  }
+}
+function armStallIfReady() {
+  if (micStreaming && helloSeen) armStall();
+}
+function armStall() {
+  disarmStall();
+  stallTimer = setTimeout(() => {
+    stallTimer = null;
+    if (pill.className === "waiting") setStatus("stalled");
+  }, STALL_MS);
+}
+
+const CELLS = 20;
+for (let i = 0; i < CELLS; i++) meterEl.appendChild(document.createElement("i"));
+let level = 0;
+
+function meter(peak) {
+  level = Math.max(peak, level * 0.7);
+  const db = level > 0 ? 20 * Math.log10(level) : -Infinity;
+  const filled = Math.max(0, Math.min(CELLS, ((db + 60) / 60) * CELLS));
+  const color = db >= -6 ? "var(--red)" : db >= -12 ? "var(--yellow)" : db > -60 ? "var(--green)" : "var(--grey)";
+  const cells = [...meterEl.children];
+  for (let i = 0; i < cells.length; i++) {
+    const frac = Math.max(0, Math.min(1, filled - i));
+    cells[i].style.height = Math.max(2, frac * 28) + "px";
+    cells[i].style.background = color;
+  }
+}
+
+let speaking = null;
+function setSpeaking(v) {
+  speaking = v;
+  speechEl.textContent = v === null ? "speech unknown" : v ? "🎙️ talking" : "· no speech";
+}
+
+// -- verdict card -------------------------------------------------------------
+
+// One emoji per feeling level so the verdict card can distinguish like from love.
+const FEELING_EMOJI = {
+  hate: "🧀🤮",
+  dislike: "🧀🙁",
+  meh: "🧀😐",
+  like: "🧀🙂",
+  love: "🧀❤️",
+};
+
+function renderVerdict(v) {
+  if (!v.talking) {
+    verdictEl.className = "";
+    verdictEl.textContent = "— not cheese";
+    return;
+  }
+  const emoji = FEELING_EMOJI[v.feeling] ?? "🧀😐";
+  const sentiment = v.feeling === "meh" ? "neutral sentiment" : `you ${v.feeling} it`;
+  verdictEl.className = v.feeling;
+  verdictEl.innerHTML =
+    `<div class="big">🧀 CHEESE</div>` +
+    `<div class="detail"><span class="kind">${v.kind}</span> (${v.p.toFixed(2)}) · ${emoji} ${sentiment} (${v.score.toFixed(1)})</div>`;
+}
+
+// -- capture: mic → 24 kHz PCM16, 40 ms frames --------------------------------
+
+const WORKLET = `
+class Capture extends AudioWorkletProcessor {
+  constructor() { super(); this.buf = []; }
+  process(inputs) {
+    const ch = inputs[0] && inputs[0][0];
+    if (ch) {
+      for (let i = 0; i < ch.length; i++) this.buf.push(ch[i]);
+      while (this.buf.length >= 960) {
+        const frame = this.buf.splice(0, 960);
+        const pcm = new Int16Array(960);
+        let peak = 0;
+        for (let i = 0; i < 960; i++) {
+          const s = Math.max(-1, Math.min(1, frame[i]));
+          pcm[i] = Math.round(s * 32767);
+          peak = Math.max(peak, Math.abs(s));
+        }
+        this.port.postMessage({ pcm: pcm.buffer, peak }, [pcm.buffer]);
+      }
+    }
+    return true;
+  }
+}
+registerProcessor("capture", Capture);
+`;
+
+const state = { ws: null, ctx: null, stream: null, started: false };
+
+async function start() {
+  toggle.disabled = true;
+  setStatus("connecting");
+  micStreaming = false;
+  helloSeen = false;
+  try {
+    state.ws = new WebSocket(`wss://${location.host}/ws`);
+    state.ws.onmessage = onMessage;
+    state.ws.onclose = () => {
+      disarmStall();
+      if (state.started) {
+        setStatus("error");
+        verdictEl.textContent = "relay connection lost";
+        stop();
+      }
+    };
+    await new Promise((resolve, reject) => {
+      state.ws.onopen = resolve;
+      state.ws.onerror = () => reject(new Error("relay connection failed"));
+    });
+    state.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    state.ctx = new AudioContext({ sampleRate: 24000 });
+    if (state.ctx.sampleRate !== 24000) throw new Error("browser ignored the 24 kHz capture rate");
+    await state.ctx.audioWorklet.addModule(URL.createObjectURL(new Blob([WORKLET], { type: "text/javascript" })));
+    const node = new AudioWorkletNode(state.ctx, "capture");
+    node.port.onmessage = (e) => {
+      meter(e.data.peak);
+      if (state.ws && state.ws.readyState === WebSocket.OPEN) state.ws.send(e.data.pcm);
+    };
+    state.ctx.createMediaStreamSource(state.stream).connect(node);
+    // The relay may have closed during setup; fail so the catch block releases the microphone.
+    if (!state.ws || state.ws.readyState !== WebSocket.OPEN) throw new Error("relay connection lost");
+    state.started = true;
+    // Arm the stall timer once the mic is streaming and Sense has said hello
+    // (either may come first).
+    micStreaming = true;
+    armStallIfReady();
+    toggle.textContent = "Stop";
+    toggle.classList.add("streaming");
+  } catch (err) {
+    setStatus("error");
+    verdictEl.textContent = err.message;
+    await stop();
+  } finally {
+    toggle.disabled = false;
+  }
+}
+
+async function stop() {
+  state.started = false;
+  disarmStall();
+  if (pill.className !== "error") setStatus("stopped");
+  toggle.textContent = "Start";
+  toggle.classList.remove("streaming");
+  if (state.ws) {
+    state.ws.onmessage = null;
+    state.ws.onclose = null;
+    state.ws.close();
+    state.ws = null;
+  }
+  if (state.stream) {
+    for (const track of state.stream.getTracks()) track.stop();
+    state.stream = null;
+  }
+  if (state.ctx) {
+    await state.ctx.close().catch(() => {});
+    state.ctx = null;
+  }
+  level = 0;
+  meter(0);
+  speechEl.textContent = "speech unknown";
+  speaking = null;
+}
+
+// -- relay events ---------------------------------------------------------------
+
+function onMessage(ev) {
+  const msg = JSON.parse(ev.data);
+  if (msg.type === "hello") {
+    setStatus(msg.mode === "online" ? "waiting" : "mic-only");
+    helloSeen = msg.mode === "online";
+    armStallIfReady();
+  } else if (msg.type === "wave") {
+    disarmStall();
+    setStatus("online");
+    setSpeaking(msg.verdict.speaking);
+    renderVerdict(msg.verdict);
+  } else if (msg.type === "stats") {
+    statsEl.textContent = "stats " + JSON.stringify(msg.stats);
+  } else if (msg.type === "error") {
+    disarmStall();
+    setStatus("error");
+    verdictEl.textContent = msg.message;
+    stop();
+  } else if (msg.type === "ended") {
+    disarmStall();
+    if (msg.reason === "cap") verdictEl.textContent = "5 min cap reached — stopping";
+    stop();
+  }
+}
+
+toggle.onclick = () => (state.started ? stop() : start());
+</script>
+</body>
+</html>

package/examples/cheese_demo.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for the cheese demo's wave → verdict mapping (mirrors
+ * python/tests/test_cheese_demo.py's decision-threshold checks).
+ * Pure logic only: no sockets, no mic.
+ */
+import { describe, expect, test } from "bun:test";
+import { Result, Score, Wave, type Session } from "@urun-sh/sense";
+import { closeRelay, handleAudio, pump, toVerdict, type Relay } from "./cheese_demo.ts";
+
+function result(
+  id: string,
+  kind: "noul" | "choice",
+  value: boolean | string,
+  p: number,
+  distribution: Record<string, number>,
+): Result {
+  return new Result({ id, kind, waveId: 7, value, p, confidence: 1, distribution, top: String(value) });
+}
+
+const FEELING_LEVELS = ["hate", "dislike", "meh", "like", "love"];
+
+/** A score result whose name-keyed dist is mapped onto the feeling levels. */
+function scoreResult(dist: Record<string, number>): Score {
+  const probs: Record<string, number> = {};
+  for (const [name, p] of Object.entries(dist)) {
+    probs[String(FEELING_LEVELS.indexOf(name))] = p;
+  }
+  return new Score({ id: "feeling", waveId: 7, probs, levels: FEELING_LEVELS, confidence: 1 });
+}
+
+function cheeseWave(p: number, kindDist: Record<string, number>, feelingDist: Record<string, number>): Wave {
+  return new Wave(7, 0, {
+    speech: result("speech", "noul", true, 1, { true: 1, false: 0 }),
+    cheese: result("cheese", "noul", true, p, { true: p, false: 1 - p }),
+    cheese_type: result("cheese_type", "choice", "cheddar", 0.99, kindDist),
+    feeling: scoreResult(feelingDist),
+  });
+}
+
+describe("toVerdict", () => {
+  test("talking threshold: not cheese below 0.6", () => {
+    const verdict = toVerdict(cheeseWave(0.59, { cheddar: 0.9 }, { love: 0.9 }));
+    if (verdict.talking) throw new Error("expected talking=false at p=0.59");
+    expect(verdict.speaking).toBe(true);
+    expect("kind" in verdict).toBe(false);
+  });
+
+  test("talking threshold: cheese at exactly 0.6", () => {
+    const verdict = toVerdict(cheeseWave(0.6, { cheddar: 0.9 }, { love: 0.9, like: 0.1 }));
+    if (!verdict.talking) throw new Error("expected talking=true at p=0.6");
+    expect(verdict.p).toBe(0.6);
+    expect(verdict.kind).toBe("cheddar");
+    expect(verdict.feeling).toBe("love");
+    expect(verdict.score).toBeCloseTo(3.9);
+    expect(verdict.waveId).toBe(7);
+  });
+
+  test("kind falls back to 'unknown type' below 0.6", () => {
+    const verdict = toVerdict(cheeseWave(0.9, { cheddar: 0.59, other: 0.41 }, { love: 0.9 }));
+    if (!verdict.talking) throw new Error("expected talking=true at p=0.9");
+    expect(verdict.kind).toBe("unknown type");
+    expect(verdict.feeling).toBe("love");
+  });
+
+  test("feeling falls back to 'meh' below 0.6", () => {
+    const verdict = toVerdict(cheeseWave(0.9, { cheddar: 0.9 }, { love: 0.59, meh: 0.41 }));
+    if (!verdict.talking) throw new Error("expected talking=true at p=0.9");
+    expect(verdict.kind).toBe("cheddar");
+    expect(verdict.feeling).toBe("meh");
+  });
+
+  test("speaking follows the speech result, not the cheese detection", () => {
+    const silent = new Wave(1, 0, {
+      speech: result("speech", "noul", false, 0, { true: 0, false: 1 }),
+      cheese: result("cheese", "noul", false, 0.2, { true: 0.2, false: 0.8 }),
+      cheese_type: result("cheese_type", "choice", "cheddar", 0.5, { cheddar: 0.5 }),
+      feeling: scoreResult({ meh: 0.5 }),
+    });
+    const verdict = toVerdict(silent);
+    expect(verdict.speaking).toBe(false);
+  });
+});
+
+// -- relay lifecycle (fake session; no sockets) --------------------------------
+
+/** Minimal Session double: enough for the relay functions under test. */
+function fakeSession(opts: { connect?: () => Promise<void>; run?: () => AsyncGenerator<Wave> } = {}) {
+  const calls = { connect: 0, close: 0, run: 0, pushed: 0 as number };
+  const session = {
+    connect: opts.connect ?? (async () => {}),
+    run: opts.run ?? (async function* () {}),
+    audio: { push: () => { calls.pushed++; } },
+    close: () => { calls.close++; },
+  };
+  return { calls, session: session as unknown as Session };
+}
+
+function testRelay(session: Session | null, send: (event: unknown) => void = () => {}): Relay {
+  return {
+    session,
+    send,
+    capTimer: null,
+    done: false,
+    closed: false,
+    pending: [],
+    streaming: false,
+    wake: null,
+    end: () => {},
+  };
+}
+
+describe("relay lifecycle", () => {
+  test("frames buffer during the dial and flush in order before run()", async () => {
+    const { calls, session } = fakeSession();
+    const relay = testRelay(session);
+    const runPromise = pump(relay);
+    handleAudio(relay, new Uint8Array(4));
+    handleAudio(relay, new Uint8Array(8));
+    expect(relay.pending.length).toBe(2); // still dialing: buffered, not pushed
+    expect(calls.pushed).toBe(0);
+    await runPromise;
+    expect(calls.pushed).toBe(2); // flushed before the run loop consumed them
+    expect(relay.pending.length).toBe(0);
+    expect(relay.streaming).toBe(true);
+  });
+
+  test("pump stops when the client leaves during the dial", async () => {
+    let runStarted = false;
+    const { calls, session } = fakeSession({
+      run: async function* () {
+        runStarted = true;
+        yield* [];
+      },
+    });
+    const relay = testRelay(session);
+    const runPromise = pump(relay);
+    closeRelay(relay); // the browser socket closes mid-dial
+    await runPromise;
+    expect(relay.closed).toBe(true);
+    expect(runStarted).toBe(false); // the upstream session was shut down, not left open
+    expect(calls.close).toBeGreaterThan(0);
+  });
+
+  test("pump stops when the client leaves during the frame wait", async () => {
+    let runStarted = false;
+    const { calls, session } = fakeSession({
+      run: async function* () {
+        runStarted = true;
+        yield* [];
+      },
+    });
+    const relay = testRelay(session);
+    const runPromise = pump(relay);
+    await new Promise((r) => setTimeout(r, 5)); // let the pump reach the frame wait
+    expect(relay.wake).not.toBeNull();
+    closeRelay(relay);
+    await runPromise;
+    expect(runStarted).toBe(false);
+    expect(calls.close).toBeGreaterThan(0);
+  });
+
+  test("handleAudio drops frames after close", () => {
+    const { calls, session } = fakeSession();
+    const relay = testRelay(session);
+    closeRelay(relay);
+    handleAudio(relay, new Uint8Array(4));
+    expect(relay.pending.length).toBe(0);
+    expect(calls.pushed).toBe(0);
+  });
+
+  test("pending buffer overflow ends the relay instead of growing unboundedly", () => {
+    const sent: unknown[] = [];
+    let ended = false;
+    const { calls, session } = fakeSession();
+    const relay = testRelay(session, (e) => sent.push(e));
+    relay.end = () => { ended = true; };
+    const big = new Uint8Array(1_100_000); // > MAX_PENDING_BYTES on its own
+    handleAudio(relay, big);
+    expect(ended).toBe(true);
+    expect(relay.pending.length).toBe(0);
+    expect(calls.pushed).toBe(0);
+    expect(sent.some((e) => (e as { type: string }).type === "error")).toBe(true);
+  });
+
+  test("closeRelay is idempotent: only the first close releases the slot", () => {
+    const { session } = fakeSession();
+    const relay = testRelay(session);
+    expect(closeRelay(relay)).toBe(true);
+    expect(closeRelay(relay)).toBe(false);
+  });
+});