@kuralle-syrinx/server-websocket 2.1.0

package/src/json-message.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+
+export function parseJsonRecord(text: string, name: string): Record<string, unknown> {
+  const parsed = JSON.parse(text) as unknown;
+  if (!isRecord(parsed)) throw new Error(`${name} must be an object`);
+  return parsed;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function optionalRecord(value: unknown, name: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) throw new Error(`${name} must be a JSON object`);
+  return value;
+}
+
+export function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+export function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+export function optionalStringOrNumber(value: unknown, name: string): string | number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  throw new Error(`${name} must be a non-empty string or finite number`);
+}

package/src/outbound-playout-pipeline.test.ts

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: MIT
+
+import { EventEmitter } from "node:events";
+import { describe, expect, it } from "vitest";
+import WebSocket from "ws";
+import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
+import { pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
+import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+
+function createMockSocket(): WebSocket {
+  const emitter = new EventEmitter();
+  let readyState: number = WebSocket.OPEN;
+  return {
+    get readyState() {
+      return readyState;
+    },
+    close: () => {
+      readyState = WebSocket.CLOSED;
+      emitter.emit("close");
+    },
+    terminate: () => {
+      readyState = WebSocket.CLOSED;
+      emitter.emit("close");
+    },
+    once: (event: string, handler: () => void) => {
+      emitter.once(event, handler);
+    },
+    off: (event: string, handler: () => void) => {
+      emitter.off(event, handler);
+    },
+  } as WebSocket;
+}
+
+function wireTestPipeline(socket: WebSocket): {
+  readonly session: VoiceAgentSession;
+  readonly handle: ReturnType<typeof wireTelephonyOutboundPipeline>;
+  readonly disposers: Array<() => void>;
+} {
+  const session = new VoiceAgentSession({ plugins: {} });
+  void session.start();
+  const disposers: Array<() => void> = [];
+  const handle = wireTelephonyOutboundPipeline({
+    session,
+    socket,
+    disposers,
+    outboundFrameDurationMs: 20,
+    maxQueuedOutputAudioMs: 30_000,
+    callbacks: {
+      carrierLabel: "test",
+      getContextId: () => "turn-drain",
+      isActive: () => true,
+      encodeFrames: (audio) => [{
+        contextId: "turn-drain",
+        send: () => true,
+      }],
+      onInterrupt: () => undefined,
+      onDrain: () => undefined,
+      onStop: () => undefined,
+    },
+  });
+  return { session, handle, disposers };
+}
+
+function makeFrames(count: number): Array<{ contextId: string; send: () => boolean }> {
+  return Array.from({ length: count }, () => ({
+    contextId: "turn-drain",
+    send: () => true,
+  }));
+}
+
+describe("wireTelephonyOutboundPipeline.interrupt.tts", () => {
+  it("clears playout and emits interrupt_onset_to_media_silent_ms", async () => {
+    const socket = createMockSocket();
+    const { session, disposers } = wireTestPipeline(socket);
+    const mediaSilentMetrics: Array<{ name: string; value: string }> = [];
+
+    session.bus.on("metric.conversation", (pkt) => {
+      const metric = pkt as unknown as { name: string; value: string };
+      if (metric.name === "test.interrupt_onset_to_media_silent_ms") mediaSilentMetrics.push(metric);
+    });
+
+    const onset = Date.now() - 25;
+    session.bus.push(Route.Critical, {
+      kind: "interrupt.tts",
+      contextId: "turn-drain",
+      timestampMs: onset,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(mediaSilentMetrics).toEqual([
+      expect.objectContaining({
+        name: "test.interrupt_onset_to_media_silent_ms",
+        value: expect.stringMatching(/^\d+$/),
+      }),
+    ]);
+    expect(Number(mediaSilentMetrics[0]!.value)).toBeGreaterThanOrEqual(0);
+
+    for (const dispose of disposers) dispose();
+  });
+});
+
+describe("wireTelephonyOutboundPipeline overflow", () => {
+  it("drops the overflow tail at the cap without stopping playout or closing the socket", async () => {
+    const socket = createMockSocket();
+    const session = new VoiceAgentSession({ plugins: {} });
+    await session.start();
+    const disposers: Array<() => void> = [];
+    const stops: string[] = [];
+    const discardedMetrics: Array<{ name: string; value: string }> = [];
+    let encodeCall = 0;
+
+    wireTelephonyOutboundPipeline({
+      session,
+      socket,
+      disposers,
+      outboundFrameDurationMs: 20,
+      maxQueuedOutputAudioMs: 200,
+      callbacks: {
+        carrierLabel: "test",
+        getContextId: () => "turn-drain",
+        isActive: () => true,
+        encodeFrames: () => {
+          encodeCall += 1;
+          return makeFrames(encodeCall === 1 ? 10 : 2);
+        },
+        onInterrupt: () => undefined,
+        onDrain: () => undefined,
+        onStop: (reason) => {
+          stops.push(reason);
+        },
+      },
+    });
+    session.bus.on("metric.conversation", (pkt) => {
+      const metric = pkt as unknown as { name: string; value: string };
+      if (metric.name === "test.overflow_playout_cleared_ms") {
+        discardedMetrics.push(metric);
+      }
+    });
+
+    session.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "turn-drain",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([1, 2, 3, 4]),
+      sampleRateHz: 8000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    session.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "turn-drain",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([5, 6, 7, 8]),
+      sampleRateHz: 8000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(stops).toEqual([]); // overflow is non-fatal — playout continues
+    expect(discardedMetrics).toEqual([
+      expect.objectContaining({
+        name: "test.overflow_playout_cleared_ms",
+        value: expect.stringMatching(/^\d+$/),
+      }),
+    ]);
+    expect(Number(discardedMetrics[0]!.value)).toBeGreaterThan(0);
+    expect(socket.readyState).toBe(WebSocket.OPEN);
+
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+});
+
+describe("wireTelephonyOutboundPipeline.drainAndClose", () => {
+  it("resolves immediately when the playout queue is idle", async () => {
+    const socket = createMockSocket();
+    const { handle, disposers } = wireTestPipeline(socket);
+
+    const startedAt = Date.now();
+    await handle.drainAndClose(socket, Date.now() + 30_000);
+    expect(Date.now() - startedAt).toBeLessThan(500);
+
+    for (const dispose of disposers) dispose();
+  });
+
+  it("settles promptly when the socket closes before queued playout control runs", async () => {
+    const socket = createMockSocket();
+    const { session, handle, disposers } = wireTestPipeline(socket);
+
+    const longAudio = pcm16SamplesToBytes(new Int16Array(8000 * 2));
+    session.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "turn-drain",
+      timestampMs: Date.now(),
+      audio: longAudio,
+      sampleRateHz: 8000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const startedAt = Date.now();
+    const drainPromise = handle.drainAndClose(socket, Date.now() + 30_000);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    socket.close();
+    await drainPromise;
+
+    expect(Date.now() - startedAt).toBeLessThan(500);
+
+    for (const dispose of disposers) dispose();
+  });
+});

package/src/outbound-playout-pipeline.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+
+import { Route, type InterruptTtsPacket, type TextToSpeechAudioPacket, type TextToSpeechEndPacket, type VoiceAgentSession } from "@kuralle-syrinx/core";
+import { WebSocket } from "ws";
+import type { PacedPlayoutFrame } from "./paced-playout.js";
+import { PacedPlayoutQueue } from "./paced-playout.js";
+import { PlayoutProgressEmitter } from "./playout-progress.js";
+import { closeWebSocketWithFallback } from "./websocket-close.js";
+import { requireTtsAudioSampleRate } from "./transport-helpers.js";
+
+export interface TelephonyOutboundCallbacks {
+  readonly carrierLabel: string;
+  getContextId(): string;
+  isActive(): boolean;
+  encodeFrames(audio: Uint8Array, sourceSampleRateHz: number, contextId: string): PacedPlayoutFrame[];
+  onInterrupt(contextId: string): void;
+  onDrain(contextId: string, playout: PacedPlayoutQueue, progress: PlayoutProgressEmitter): void;
+  onStop(reason: "send_buffer"): void;
+  onClear?(): void;
+}
+
+export interface TelephonyOutboundHandle {
+  clearPlayout(reason: string): void;
+  drainAndClose(socket: WebSocket, deadlineMs: number): Promise<void>;
+}
+
+export function wireTelephonyOutboundPipeline(args: {
+  readonly session: VoiceAgentSession;
+  readonly socket: WebSocket;
+  readonly disposers: Array<() => void>;
+  readonly outboundFrameDurationMs: number;
+  readonly maxQueuedOutputAudioMs: number;
+  readonly callbacks: TelephonyOutboundCallbacks;
+}): TelephonyOutboundHandle {
+  const { session, socket, disposers, outboundFrameDurationMs, maxQueuedOutputAudioMs, callbacks } = args;
+
+  const recordDiscardedPlayout = (discardedMs: number, reason: string): void => {
+    if (discardedMs <= 0) return;
+    session.bus.push(Route.Critical, {
+      kind: "record.assistant_audio",
+      contextId: callbacks.getContextId(),
+      timestampMs: Date.now(),
+      audio: new Uint8Array(0),
+      truncate: true,
+    });
+    session.bus.push(Route.Critical, {
+      kind: "metric.conversation",
+      contextId: callbacks.getContextId(),
+      timestampMs: Date.now(),
+      name: `${callbacks.carrierLabel}.${reason}_playout_cleared_ms`,
+      value: String(discardedMs),
+    });
+  };
+
+  const playoutProgress = new PlayoutProgressEmitter(session.bus);
+  const playout = new PacedPlayoutQueue(
+    outboundFrameDurationMs,
+    maxQueuedOutputAudioMs,
+    (droppedMs) => {
+      // Non-fatal: the tail that did not fit was dropped; playout continues.
+      recordDiscardedPlayout(droppedMs, "overflow");
+    },
+    (discardedMs) => {
+      callbacks.onStop("send_buffer");
+      recordDiscardedPlayout(discardedMs, "send_buffer");
+    },
+    (lateMs) => {
+      session.bus.push(Route.Background, {
+        kind: "metric.conversation",
+        contextId: callbacks.getContextId(),
+        timestampMs: Date.now(),
+        name: `${callbacks.carrierLabel}.pacer_deadline_miss`,
+        value: String(lateMs),
+      });
+    },
+    playoutProgress.onFramePlayed,
+  );
+  const interruptedContextIds = new Set<string>();
+
+  disposers.push(
+    () => playout.close(),
+    session.bus.on("interrupt.tts", (pkt) => {
+      const interrupt = pkt as InterruptTtsPacket;
+      interruptedContextIds.add(interrupt.contextId);
+      playoutProgress.discard(interrupt.contextId);
+      playout.clearInterruptible();
+      callbacks.onClear?.();
+      callbacks.onInterrupt(interrupt.contextId);
+      session.bus.push(Route.Background, {
+        kind: "metric.conversation",
+        contextId: interrupt.contextId,
+        timestampMs: Date.now(),
+        name: `${callbacks.carrierLabel}.interrupt_onset_to_media_silent_ms`,
+        value: String(Math.max(0, Date.now() - interrupt.timestampMs)),
+      });
+    }),
+    session.bus.on("tts.audio", (pkt) => {
+      const audioPacket = pkt as TextToSpeechAudioPacket;
+      if (interruptedContextIds.has(audioPacket.contextId)) return;
+      if (!callbacks.isActive()) return;
+      if (socket.readyState !== WebSocket.OPEN) {
+        session.bus.push(Route.Background, {
+          kind: "metric.conversation",
+          contextId: audioPacket.contextId,
+          timestampMs: Date.now(),
+          name: "websocket.send_after_close",
+          value: "1",
+        });
+        return;
+      }
+      const frames = callbacks.encodeFrames(
+        audioPacket.audio,
+        requireTtsAudioSampleRate(audioPacket.sampleRateHz),
+        audioPacket.contextId,
+      );
+      playout.enqueue(frames);
+    }),
+    session.bus.on("tts.end", (pkt) => {
+      const end = pkt as TextToSpeechEndPacket;
+      if (interruptedContextIds.has(end.contextId)) return;
+      if (!callbacks.isActive()) return;
+      callbacks.onDrain(end.contextId, playout, playoutProgress);
+    }),
+  );
+
+  return {
+    clearPlayout: (reason: string) => {
+      callbacks.onClear?.();
+      recordDiscardedPlayout(playout.clear(), reason);
+    },
+    drainAndClose: (socket: WebSocket, deadlineMs: number): Promise<void> => {
+      if (socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING) {
+        return Promise.resolve();
+      }
+      return new Promise<void>((resolve) => {
+        let settled = false;
+        let deadlineTimer: ReturnType<typeof setTimeout>;
+        const settle = () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(deadlineTimer);
+          socket.off("close", onSocketClose);
+          resolve();
+        };
+
+        const onSocketClose = (): void => {
+          settle();
+        };
+
+        deadlineTimer = setTimeout(() => {
+          if (socket.readyState !== WebSocket.CLOSED && socket.readyState !== WebSocket.CLOSING) {
+            socket.terminate();
+          }
+          settle();
+        }, Math.max(0, deadlineMs - Date.now()));
+        (deadlineTimer as NodeJS.Timeout).unref?.();
+        socket.once("close", onSocketClose);
+
+        // enqueueControl may run synchronously when the queue is idle — register timers first.
+        playout.enqueueControl(() => {
+          closeWebSocketWithFallback(socket, 1001, "server going away");
+          settle();
+        });
+      });
+    },
+  };
+}

package/src/paced-playout.test.ts

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PacedPlayoutQueue, type PacedPlayoutFrame } from "./paced-playout.js";
+
+function makeFrame(onSend?: () => void): PacedPlayoutFrame {
+  return { send: () => { onSend?.(); } };
+}
+
+describe("PacedPlayoutQueue — drift-corrected scheduling", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("drift-locked cadence: second frame fires at T+FRAME_MS despite slow first send", () => {
+    vi.setSystemTime(0);
+    const FRAME_MS = 20;
+    const sendTimes: number[] = [];
+
+    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
+
+    // First send() runs outside tick() context (maybePump → pump is called
+    // synchronously from enqueue). Safe to call setSystemTime here.
+    // Simulates 8ms of work, so without drift-correction the second timer
+    // would be scheduled at callAt = 0+8+20 = 28 instead of 20.
+    queue.enqueue([
+      {
+        send: () => {
+          sendTimes.push(Date.now());
+          vi.setSystemTime(8);
+        },
+      },
+      { send: () => { sendTimes.push(Date.now()); } },
+    ]);
+
+    // With drift-correction: delay = max(0, 20 - 8) = 12, callAt = 8+12 = 20
+    // Without drift-correction: delay = 20, callAt = 8+20 = 28
+    vi.advanceTimersByTime(20); // covers [8, 28] — fires callAt=20 but NOT callAt=28
+
+    expect(sendTimes).toHaveLength(2);
+    expect(sendTimes[0]).toBe(0);
+    expect(sendTimes[1]).toBe(20); // wall-clock-locked
+  });
+
+  it("fires onDeadlineMiss with correct lateMs when pump wakes up past tolerance", () => {
+    vi.setSystemTime(0);
+    const FRAME_MS = 20;
+    const misses: number[] = [];
+
+    const queue = new PacedPlayoutQueue(
+      FRAME_MS,
+      10_000,
+      () => {},
+      () => {},
+      (lateMs) => misses.push(lateMs),
+    );
+
+    // First send() advances the clock to 30ms (past the T+20 next deadline).
+    // This causes the next timer to be scheduled with delay=0, callAt=30.
+    // When that timer fires, now=30 and nextDeadlineMs=20, so lateMs=10 > 5.
+    queue.enqueue([
+      {
+        send: () => {
+          vi.setSystemTime(30);
+        },
+      },
+      makeFrame(),
+    ]);
+
+    vi.advanceTimersByTime(1); // fire the 0ms timer (callAt=30, advances 30→31)
+
+    expect(misses).toHaveLength(1);
+    expect(misses[0]).toBe(10); // 30 - 20 = 10ms late
+  });
+
+  it("does NOT fire onDeadlineMiss when pump fires on time (within tolerance)", () => {
+    vi.setSystemTime(0);
+    const FRAME_MS = 20;
+    const misses: number[] = [];
+
+    const queue = new PacedPlayoutQueue(
+      FRAME_MS,
+      10_000,
+      () => {},
+      () => {},
+      (lateMs) => misses.push(lateMs),
+    );
+
+    queue.enqueue([makeFrame(), makeFrame(), makeFrame()]);
+
+    // Exact FRAME_MS advances — timers fire precisely on their deadlines.
+    vi.advanceTimersByTime(FRAME_MS);
+    vi.advanceTimersByTime(FRAME_MS);
+
+    expect(misses).toHaveLength(0);
+  });
+
+  it("resets deadline tracking after clear() so next burst starts fresh with no spurious misses", () => {
+    vi.setSystemTime(0);
+    const FRAME_MS = 20;
+    const misses: number[] = [];
+
+    const queue = new PacedPlayoutQueue(
+      FRAME_MS,
+      10_000,
+      () => {},
+      () => {},
+      (lateMs) => misses.push(lateMs),
+    );
+
+    queue.enqueue([makeFrame(), makeFrame()]);
+    vi.advanceTimersByTime(FRAME_MS);
+    queue.clear();
+
+    // Simulate a 5 s inter-utterance gap. Without clear() resetting the
+    // deadline, the next frame would appear ~5000ms late and trigger a miss.
+    vi.advanceTimersByTime(5_000);
+
+    // New burst with no simulated send overhead.
+    queue.enqueue([makeFrame(), makeFrame()]);
+
+    vi.advanceTimersByTime(FRAME_MS);
+
+    // The first frame of a new burst sets the baseline (nextDeadlineMs was 0),
+    // and the second frame fires on schedule — neither should miss.
+    expect(misses).toHaveLength(0);
+  });
+
+  it("re-baselines after a natural drain (no clear) so an inter-sentence gap is not a false miss", () => {
+    vi.setSystemTime(0);
+    const FRAME_MS = 20;
+    const misses: number[] = [];
+
+    const queue = new PacedPlayoutQueue(
+      FRAME_MS,
+      10_000,
+      () => {},
+      () => {},
+      (lateMs) => misses.push(lateMs),
+    );
+
+    // First burst of two frames drains naturally — the queue empties with NO
+    // clear() call (clear() only runs on overflow/send-failure/interrupt).
+    queue.enqueue([makeFrame(), makeFrame()]);
+    vi.advanceTimersByTime(FRAME_MS);
+
+    // Natural inter-sentence gap: no audio, no clear().
+    vi.advanceTimersByTime(2_000);
+
+    // Next burst. Its first frame must re-baseline rather than read the stale
+    // pre-gap deadline as a ~2000ms miss.
+    queue.enqueue([makeFrame(), makeFrame()]);
+    vi.advanceTimersByTime(FRAME_MS);
+
+    expect(misses).toHaveLength(0);
+  });
+
+  it("does not advance the playout deadline by frameDurationMs after a 0 ms control frame", () => {
+    const FRAME_MS = 20;
+    let sends = 0;
+    const misses: number[] = [];
+
+    const queue = new PacedPlayoutQueue(
+      FRAME_MS,
+      10_000,
+      () => {},
+      () => {},
+      (lateMs) => misses.push(lateMs),
+    );
+
+    queue.enqueue([{ send: () => { sends += 1; } }]);
+    expect(sends).toBe(1);
+    queue.enqueueControl(() => { sends += 1; });
+    queue.enqueue([{ send: () => { sends += 1; } }]);
+    vi.advanceTimersByTime(FRAME_MS);
+    expect(sends).toBe(3);
+    vi.advanceTimersByTime(FRAME_MS);
+    expect(sends).toBe(3);
+    expect(misses).toHaveLength(0);
+  });
+
+  it("backward-compatible: works without onDeadlineMiss callback", () => {
+    const queue = new PacedPlayoutQueue(20, 10_000, () => {});
+    expect(() => {
+      queue.enqueue([makeFrame(), makeFrame()]);
+      vi.advanceTimersByTime(40);
+    }).not.toThrow();
+  });
+
+  it("clearInterruptible drops audio but retains an uninterruptible control frame", () => {
+    const FRAME_MS = 20;
+    const sends: string[] = [];
+    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
+
+    // a1 sends synchronously on enqueue; a2 + a3 remain queued behind the pacer timer.
+    queue.enqueue([
+      { send: () => { sends.push("a1"); } },
+      { send: () => { sends.push("a2"); } },
+      { send: () => { sends.push("a3"); } },
+    ]);
+    expect(sends).toEqual(["a1"]);
+
+    queue.enqueueControl(() => { sends.push("ctrl"); }, { uninterruptible: true });
+
+    const discarded = queue.clearInterruptible();
+
+    // a2 + a3 (interruptible audio) dropped; the uninterruptible control survives and is pumped.
+    expect(discarded).toBe(2 * FRAME_MS);
+    expect(sends).toEqual(["a1", "ctrl"]);
+
+    // No dropped audio is ever replayed on later ticks.
+    vi.advanceTimersByTime(FRAME_MS * 5);
+    expect(sends).toEqual(["a1", "ctrl"]);
+  });
+
+  it("clearInterruptible never replays dropped audio frames", () => {
+    const FRAME_MS = 20;
+    const sends: string[] = [];
+    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
+    queue.enqueue([
+      { send: () => { sends.push("a1"); } },
+      { send: () => { sends.push("a2"); } },
+      { send: () => { sends.push("a3"); } },
+    ]);
+    queue.clearInterruptible();
+    vi.advanceTimersByTime(FRAME_MS * 5);
+    expect(sends).toEqual(["a1"]); // a2/a3 never sent — no speech replay after interrupt
+  });
+
+  it("clearInterruptible drops unmarked control frames (back-compat with clear)", () => {
+    const FRAME_MS = 20;
+    const sends: string[] = [];
+    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
+    queue.enqueue([
+      { send: () => { sends.push("a1"); } },
+      { send: () => { sends.push("a2"); } },
+    ]);
+    queue.enqueueControl(() => { sends.push("ctrl"); }); // default = interruptible
+    queue.clearInterruptible();
+    vi.advanceTimersByTime(FRAME_MS * 5);
+    expect(sends).toEqual(["a1"]); // a2 + unmarked control both dropped
+  });
+});