@specific.dev/spectest 0.110.0 → 0.112.0

package/dist/phone.js

@@ -0,0 +1,343 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, open, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { captureRecording, recordStep, reserveEvent } from "./recorder.js";
+import { deepUnwrap } from "./inspect.js";
+const MAX_RECORDING_BYTES = 96 * 1024 * 1024;
+const parked = new Map();
+export async function phoneRecordingChunk(id, offset, limit) {
+    const entry = parked.get(id);
+    if (!entry)
+        throw new Error("Unknown phone recording");
+    const start = Number(offset ?? 0), count = Number(limit ?? 6 * 1024 * 1024);
+    if (!Number.isSafeInteger(start) || start < 0 || start > entry.bytes || !Number.isSafeInteger(count) || count < 1 || count > 6 * 1024 * 1024)
+        throw new Error("Invalid phone recording range");
+    const file = await open(entry.path, "r");
+    try {
+        const buffer = Buffer.alloc(Math.min(count, entry.bytes - start));
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, start);
+        return { b64: buffer.subarray(0, bytesRead).toString("base64"), offset: start, total: entry.bytes };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function releasePhoneRecording(id) {
+    const entry = parked.get(id);
+    if (entry) {
+        parked.delete(id);
+        await rm(entry.path, { force: true });
+        if (![...parked.values()].some(p => p.directory === entry.directory))
+            await rm(entry.directory, { recursive: true, force: true });
+    }
+    return { released: true };
+}
+class PhoneSession {
+    options;
+    caseStart;
+    reserveCall;
+    pending = new Map();
+    nextId = 0;
+    closed = false;
+    failure;
+    cancellation = new AbortController();
+    tail = Promise.resolve();
+    child;
+    exited;
+    closing;
+    directory;
+    activeCall;
+    calls = new Map();
+    constructor(options, caseStart, reserveCall) {
+        this.options = options;
+        this.caseStart = caseStart;
+        this.reserveCall = reserveCall;
+        if (!/^[a-zA-Z0-9.-]+(?::\d{1,5})?$/.test(options.endpoint))
+            throw new Error("phone.endpoint must be a hostname or IPv4 address with optional port");
+        if (!/^sip:[^\s<>]+$/.test(options.from))
+            throw new Error("phone.from must be a sip: URI");
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0))
+            throw new Error("phone.timeoutMs must be positive");
+        this.child = spawn(process.env.SPECTEST_PHONE_PYTHON ?? "/opt/spectest/phone/bin/python", [fileURLToPath(new URL("./harness/phone.py", import.meta.url))], { stdio: ["pipe", "pipe", "pipe"] });
+        this.exited = new Promise(resolve => { this.child.once("close", () => resolve()); });
+        // Native logs can contain authentication headers. Never record them.
+        this.child.stderr.resume();
+        createInterface({ input: this.child.stdout }).on("line", line => {
+            let reply;
+            try {
+                reply = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (reply.event === "recording" && reply.sessionId) {
+                const call = this.calls.get(reply.sessionId);
+                if (call)
+                    call.recording = { id: reply.sessionId, startedAtMs: reply.startedAtMs - this.caseStart, duration: reply.duration, bytes: reply.bytes, peaks: reply.peaks, callerPeaks: reply.callerPeaks, recipientPeaks: reply.recipientPeaks, contentType: reply.contentType, encodingFinalizeMs: reply.encodingFinalizeMs, error: reply.error };
+                return;
+            }
+            const waiter = this.pending.get(reply.id);
+            if (!waiter)
+                return;
+            if (typeof reply.offset === "number" && Number.isFinite(reply.offset) && reply.offset >= 0) {
+                waiter.position?.(reply.event ?? "operation_ended", reply.offset);
+            }
+            if (reply.event === "speech_started" || reply.event === "operation_started") {
+                return;
+            }
+            clearTimeout(waiter.timer);
+            this.pending.delete(reply.id);
+            if (reply.error)
+                waiter.reject(new Error(reply.error));
+            else
+                waiter.resolve(reply);
+        });
+        this.child.on("error", () => this.fail(new Error("Phone runtime unavailable. Rebuild the golden image with phone support.")));
+        this.child.on("exit", () => this.fail(new Error("Phone runtime exited")));
+        this.child.stdin.on("error", () => this.fail(new Error("Phone runtime input closed")));
+    }
+    fail(error) {
+        this.closed = true;
+        this.failure ??= error;
+        this.cancellation.abort(this.failure);
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+        this.pending.clear();
+    }
+    request(action, data = {}, timeout = this.options.timeoutMs ?? 30_000, position) {
+        if (this.closed)
+            return Promise.reject(new Error("Phone is closed"));
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout);
+            this.pending.set(id, { resolve, reject, timer, position });
+            this.child.stdin.write(JSON.stringify({ id, action, ...data }) + "\n");
+        });
+    }
+    async initialize() {
+        this.directory = await mkdtemp(join(tmpdir(), "spectest-phone-"));
+        if (this.closed)
+            throw this.failure ?? new Error("Phone is closed");
+        await this.request("open", { ...this.options, directory: this.directory }, 60_000);
+        return this;
+    }
+    async waitForResponse(options) {
+        const timeout = 30_000;
+        const deadline = performance.now() + timeout;
+        const controller = new AbortController();
+        const cancel = () => controller.abort(this.failure ?? new Error("Phone closed"));
+        this.cancellation.signal.addEventListener("abort", cancel, { once: true });
+        if (this.closed)
+            cancel();
+        const timer = setTimeout(() => controller.abort(new Error(`Phone response wait timed out after ${timeout}ms`)), timeout);
+        const aborted = new Promise((_, reject) => {
+            const rejectAbort = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", rejectAbort, { once: true });
+            if (controller.signal.aborted)
+                rejectAbort();
+        });
+        // Probes are observations: suppress their internal events without affecting
+        // concurrent phones, and discard late results after timeout/case cleanup.
+        const branch = captureRecording();
+        try {
+            return await Promise.race([aborted, branch.run(async () => {
+                    let response;
+                    if (options.waitFor) {
+                        for (;;) {
+                            controller.signal.throwIfAborted();
+                            const ready = deepUnwrap(await options.waitFor());
+                            controller.signal.throwIfAborted();
+                            if (ready) {
+                                if (typeof ready === "string")
+                                    response = ready;
+                                break;
+                            }
+                            await delay(100, undefined, { signal: controller.signal });
+                        }
+                    }
+                    controller.signal.throwIfAborted();
+                    const remaining = Math.max(1, deadline - performance.now());
+                    const reply = await this.request("wait_silence", { silenceMs: 700, timeoutMs: remaining }, remaining + 1000);
+                    return { ...reply, response };
+                })]);
+        }
+        finally {
+            clearTimeout(timer);
+            this.cancellation.signal.removeEventListener("abort", cancel);
+            controller.abort();
+            branch.finish(false);
+        }
+    }
+    operation(action, title, data = {}, timeout, options) {
+        if (this.closed)
+            return Promise.reject(new Error("Phone is closed"));
+        const work = this.tail.then(async () => {
+            if (this.closed)
+                throw new Error("Phone is closed");
+            const reservation = reserveEvent(), start = Date.now();
+            if (action === "call") {
+                if (this.activeCall && !this.calls.get(this.activeCall)?.recording)
+                    throw new Error("Already in a call; hang up before dialing again");
+                this.reserveCall();
+                this.activeCall = randomUUID();
+                this.calls.set(this.activeCall, { started: start, steps: [] });
+                data = { ...data, sessionId: this.activeCall };
+            }
+            const text = action === "say" ? data.text : "";
+            const blocks = [];
+            let step;
+            if (this.activeCall) {
+                const block = { type: "audio", sessionId: this.activeCall, text, start: 0, end: 0, duration: 0, peaks: [] };
+                if (action === "call" && options?.waitFor)
+                    block.waitedForSpeech = true;
+                step = { block };
+                this.calls.get(this.activeCall).steps.push(step);
+                // Retain the boundary for recording finalization, without rendering a
+                // player on the hangup step.
+                if (action !== "hangup")
+                    blocks.push(block);
+            }
+            else if (text)
+                blocks.push({ type: "text", text });
+            try {
+                let reply = await this.request(action, data, timeout, (event, offset) => {
+                    if (!step)
+                        return;
+                    if (event === "speech_started")
+                        step.playbackStart = offset;
+                    if (event === "operation_started") {
+                        step.playbackStart = offset;
+                        const steps = this.calls.get(this.activeCall).steps;
+                        const previous = steps.at(-2);
+                        // Dialing owns the greeting/idle audio up to the next operation.
+                        if (previous && previous.playbackEnd === undefined)
+                            previous.playbackEnd = offset;
+                    }
+                    if (event === "operation_ended")
+                        step.playbackEnd = offset;
+                });
+                if (options?.waitFor) {
+                    const waited = await this.waitForResponse(options);
+                    reply = waited;
+                    if (step && waited.response !== undefined)
+                        step.block.response = waited.response;
+                }
+                if ((action === "say" || options?.waitFor) && step) {
+                    step.playbackEnd = reply.offset;
+                }
+                recordStep({ kind: "phone", title, blocks, status: "passed", durationMs: Date.now() - start }, reservation);
+                if (action === "hangup")
+                    this.activeCall = undefined;
+            }
+            catch (error) {
+                if ((action === "say" || action === "call") && step) {
+                    // A predicate can fail independently of the native transport. Sample
+                    // its current position too; wall time is not an audio-file offset.
+                    const position = this.closed ? undefined : await this.request("position").catch(() => undefined);
+                    step.playbackEnd = this.closed ? undefined : position?.offset ?? step.playbackEnd;
+                }
+                recordStep({ kind: "phone", title, blocks, status: "failed", error: String(error), durationMs: Date.now() - start }, reservation);
+                throw error;
+            }
+        });
+        this.tail = work.catch(() => { });
+        return work;
+    }
+    call(destination, options = {}) {
+        if (!destination || /[\s<>\r\n]/.test(destination))
+            return Promise.reject(new Error("Invalid phone destination"));
+        if (options.waitFor !== undefined && typeof options.waitFor !== "function")
+            return Promise.reject(new Error("phone.call waitFor must be a predicate"));
+        return this.operation("call", `Call ${destination}`, { destination }, undefined, options);
+    }
+    say(text, options = {}) {
+        if (!text.trim() || text.length > 2000)
+            return Promise.reject(new Error("phone.say requires 1–2,000 characters"));
+        if (options.speed !== undefined && (!Number.isFinite(options.speed) || options.speed < 0.7 || options.speed > 2))
+            return Promise.reject(new Error("Speech speed must be between 0.7 and 2"));
+        if (options.waitFor !== undefined && typeof options.waitFor !== "function")
+            return Promise.reject(new Error("phone.say waitFor must be a predicate"));
+        const { waitFor, ...voice } = options;
+        return this.operation("say", `Say ${JSON.stringify(text)}`, { ...voice, language: voice.language ?? this.options.language ?? "en", text }, 180_000, { waitFor });
+    }
+    hangup() { return this.operation("hangup", "Hang up"); }
+    close() { return this.closing ??= this.dispose(); }
+    async dispose() {
+        this.fail(new Error("Phone closed"));
+        this.child.stdin.end();
+        // EOF interrupts synthesis/playback, hangs up, and seals the recording.
+        const timer = setTimeout(() => this.child.kill("SIGKILL"), 10_000);
+        await this.exited;
+        clearTimeout(timer);
+        await this.tail;
+    }
+    async finish(record) {
+        await this.close();
+        const recordings = [];
+        for (const [id, call] of this.calls) {
+            const r = call.recording ?? { id, startedAtMs: call.started - this.caseStart, duration: 0, bytes: 0, contentType: "audio/webm", peaks: [], error: "Phone runtime exited before the call recording was finalized" };
+            const path = join(this.directory, `${id}.webm`);
+            if (!r.error) {
+                const size = (await stat(path).catch(() => null))?.size;
+                if (size !== r.bytes || r.bytes < 44 || r.bytes > MAX_RECORDING_BYTES)
+                    r.error = "Call recording is missing or exceeds the size limit";
+            }
+            // Say owns transmission through its optional response wait. Unrelated
+            // work and later idle time stay only in the continuous call recording.
+            // Dial/hangup retain the surrounding call audio (including the greeting).
+            for (let i = 0; i < call.steps.length; i++) {
+                const step = call.steps[i];
+                const end = Math.min(r.duration, step.playbackEnd ?? call.steps[i + 1]?.playbackStart ?? r.duration);
+                Object.assign(step.block, { duration: r.duration, start: Math.min(end, step.playbackStart ?? 0), end });
+            }
+            if (record && !r.error)
+                parked.set(id, { path, directory: this.directory, bytes: r.bytes });
+            recordings.push(r);
+        }
+        if (this.directory && ![...parked.values()].some(p => p.directory === this.directory))
+            await rm(this.directory, { recursive: true, force: true });
+        return record ? recordings : [];
+    }
+}
+export function phoneScope(caseStart = Date.now(), { record = true } = {}) {
+    const sessions = new Set();
+    let closed = false, calls = 0;
+    let finished;
+    // A fork inherits its parent's completed files. Discard those before opening
+    // this case's phones; the parent VM retains its own copies for archival.
+    const cleanup = (async () => {
+        // Calls from one phone share a directory; retire files sequentially so
+        // only the last release removes it.
+        for (const id of [...parked.keys()])
+            await releasePhoneRecording(id);
+    })();
+    return {
+        async open(options) {
+            await cleanup;
+            if (closed)
+                throw new Error("Phone test scope has ended");
+            const session = new PhoneSession(options, caseStart, () => { if (++calls > 8)
+                throw new Error("A case can record at most eight calls"); });
+            sessions.add(session);
+            try {
+                return await session.initialize();
+            }
+            catch (error) {
+                await session.finish(false);
+                throw error;
+            }
+        },
+        async close() { closed = true; await Promise.all([...sessions].map(s => s.close())); },
+        finish() {
+            closed = true;
+            return finished ??= Promise.all([...sessions].map(s => s.finish(record))).then(records => records.flat());
+        },
+    };
+}

package/dist/recorder.d.ts

@@ -617,6 +617,16 @@ export declare function recordEnv(ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind
  * newer SDK's step degrades to the blocks the server knows.
  */
 export type StepBlock = {
+    type: "audio";
+    sessionId: string;
+    start: number;
+    end: number;
+    text: string;
+    duration: number;
+    peaks: number[];
+    waitedForSpeech?: boolean;
+    response?: string;
+} | {
     type: "text";
     text: string;
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.110.0",
+  "version": "0.112.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/replay-websocket.ts

@@ -15,7 +15,36 @@ const MAX_PENDING = 1024;
 export type ReplayWebSocketMessage = string | Uint8Array;
 export type WebSocketKey<S = unknown> =
   | ((message: ReplayWebSocketMessage) => MatchKey)
-  | { initial: S; reduce(state: S, message: ReplayWebSocketMessage): { state: S; key: MatchKey } };
+  | { initial: S; reduce(state: S, message: ReplayWebSocketMessage): { state: S; key: MatchKey } }
+  | {
+      initial: S;
+      /** Candidate keys, not mandatory inputs. Emit multiple keys to normalize stream chunking. */
+      input(state: S, message: ReplayWebSocketMessage): { state: S } & (
+        { key: MatchKey; keys?: never } | { keys: MatchKey[]; key?: never }
+      );
+      /** Runs on real output during recording and saved output during replay.
+       * Select the latest candidate as a timing anchor during recording only. */
+      output(state: S, message: ReplayWebSocketMessage): { state: S; anchorPreviousInput: boolean };
+    };
+
+export type WebSocketMatcher = ((message: ReplayWebSocketMessage) => string | null) & {
+  candidates?: (message: ReplayWebSocketMessage) => string[];
+  output?: (message: ReplayWebSocketMessage) => boolean;
+};
+const MAX_CANDIDATE_KEYS = 65536;
+function occurrence(counts: Map<string, number>, key: string): number {
+  if (!counts.has(key) && counts.size >= MAX_CANDIDATE_KEYS) throw new Error("WebSocket candidate key limit exceeded");
+  const count = (counts.get(key) ?? 0) + 1;
+  counts.set(key, count);
+  return count;
+}
+function synchronous(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (value && typeof value === "object" && "then" in value) {
+    if (value instanceof Promise) void value.catch(() => {});
+    throw new Error(`websocketKey ${label} must be synchronous`);
+  }
+  if (!value || typeof value !== "object" || !("state" in value)) throw new Error(`websocketKey ${label} must return state`);
+}
 
 export interface WebSocketTiming {
   /** Number of emitted input keys required. Zero means connection opening. */
@@ -32,6 +61,10 @@ export interface CassetteWebSocket {
   request: CassetteRequest;
   protocol?: string;
   inputs: string[];
+  /** Only output-selected candidates are required in this mode. */
+  inputMode?: "anchors";
+  /** One-based occurrence of each selected hash in the full candidate stream. */
+  inputOccurrences?: number[];
   messages: CassetteWebSocketMessage[];
   /** Absent while recording a connection that is still open. */
   close?: WebSocketTiming & { initiator: "client" | "server"; code: number; reason: string };
@@ -39,15 +72,39 @@ export interface CassetteWebSocket {
 
 export function validateWebSocketKey<S>(key: WebSocketKey<S> | undefined): void {
   if (key === undefined || typeof key === "function") return;
-  if (!key || typeof key !== "object" || !("initial" in key) || typeof key.reduce !== "function") {
-    throw new Error("websocketKey must be a synchronous function or { initial, reduce }");
+  if (!key || typeof key !== "object" || !("initial" in key)
+    || !("reduce" in key && typeof key.reduce === "function" && !("input" in key) && !("output" in key)
+      || "input" in key && typeof key.input === "function" && "output" in key && typeof key.output === "function" && !("reduce" in key))) {
+    throw new Error("websocketKey must be a synchronous function, { initial, reduce }, or { initial, input, output }");
   }
   structuredClone(key.initial);
 }
 
 /** Clone once per connection; never retain incoming payloads. */
-export function websocketMatcher<S>(key?: WebSocketKey<S>): (message: ReplayWebSocketMessage) => string | null {
+export function websocketMatcher<S>(key?: WebSocketKey<S>): WebSocketMatcher {
   let state = key && typeof key !== "function" ? structuredClone(key.initial) : undefined;
+  if (key && typeof key === "object" && "input" in key) {
+    const input = (message: ReplayWebSocketMessage) => {
+      const next = key.input(state as S, message);
+      synchronous(next, "input");
+      if (("key" in next) === ("keys" in next) || "keys" in next && !Array.isArray(next.keys)) throw new Error("websocketKey input must return { state, key } or { state, keys }");
+      const values = "keys" in next ? next.keys! : [next.key];
+      if (values.length > MAX_PENDING) throw new Error("WebSocket candidate batch limit exceeded");
+      const hashes = values.filter(value => value !== null).map(hashKey);
+      state = next.state;
+      return hashes;
+    };
+    return Object.assign((message: ReplayWebSocketMessage) => input(message).at(-1) ?? null, {
+      candidates: input,
+      output(message: ReplayWebSocketMessage) {
+        const next = key.output(state as S, message);
+        synchronous(next, "output");
+        if (typeof next.anchorPreviousInput !== "boolean") throw new Error("websocketKey output must return { state, anchorPreviousInput }");
+        state = next.state;
+        return next.anchorPreviousInput;
+      },
+    });
+  }
   return message => {
     if (!key) return createHash("sha256").update(typeof message === "string" ? "text:" : "binary:").update(message).digest("hex");
     let value: MatchKey;
@@ -77,6 +134,16 @@ export function validateWebSocketRecording(record: CassetteWebSocket): void {
     || !Array.isArray(record.messages)) {
     throw new Error("invalid WebSocket recording: expected request, input hashes and messages");
   }
+  if (record.inputMode !== undefined && record.inputMode !== "anchors") throw new Error("invalid WebSocket input mode");
+  if (record.inputMode === "anchors") {
+    if (!Array.isArray(record.inputOccurrences) || record.inputOccurrences.length !== record.inputs.length) throw new Error("invalid WebSocket anchor occurrences");
+    const seen = new Map<string, number>();
+    record.inputs.forEach((key, index) => {
+      const count = record.inputOccurrences![index];
+      if (!Number.isSafeInteger(count) || count < 1 || count <= (seen.get(key) ?? 0)) throw new Error("invalid WebSocket anchor occurrence order");
+      seen.set(key, count);
+    });
+  } else if (record.inputOccurrences !== undefined) throw new Error("WebSocket occurrences require anchor mode");
   for (const message of record.messages) {
     if (!message || typeof message.data !== "string" || !["text", "binary"].includes(message.type)) {
       throw new Error("invalid WebSocket output message");
@@ -127,13 +194,15 @@ export interface WebSocketSession {
 
 export function replayWebSocket(args: {
   recording: CassetteWebSocket;
-  match: (message: ReplayWebSocketMessage) => string | null;
+  match: WebSocketMatcher;
   label: string;
   timeoutMs: number;
   lifetime?: FakeWebSocketLifetime;
   finished(session: WebSocketSession, error?: Error): void;
 }): { handlers: FakeWebSocketHandlers; session: WebSocketSession } {
   const { recording: record, label } = args;
+  if ((record.inputMode === "anchors") !== !!args.match.candidates) throw new Error(`${label}: websocketKey mode changed; re-record this cassette`);
+  const occurrences = new Map<string, number>();
   const lifetime = args.lifetime ?? new FakeWebSocketLifetime();
   let detach = () => {};
   let socket: FakeWebSocket | undefined;
@@ -163,25 +232,52 @@ export function replayWebSocket(args: {
     clearTimeout(deadline);
     if (position < record.inputs.length) deadline = setTimeout(() => fail(missing()), args.timeoutMs);
   };
+  const nextEvent = () => (record.messages[output] as CassetteWebSocketMessage | undefined)
+    ?? (record.close?.initiator === "server" ? record.close : undefined);
+  const starts = record.inputMode === "anchors"
+    ? [...record.messages, ...(record.close?.initiator === "server" ? [record.close] : [])]
+      .filter((event, index, events) => index === 0 || event.afterInput !== events[index - 1].afterInput)
+    : [];
+  const dueAt = (event: WebSocketTiming) => {
+    let due = barriers[event.afterInput] + event.delayMs;
+    // Input progress can be faster than the recording (e.g. cached TTS).
+    // Once a later anchor is reached, earlier output must not hold its response
+    // behind the old clock. Catch up in order, without dropping any messages.
+    for (const next of starts) {
+      if (next.afterInput > event.afterInput && barriers[next.afterInput] !== undefined) {
+        due = Math.min(due, barriers[next.afterInput] + next.delayMs);
+      }
+    }
+    return due;
+  };
   const schedule = () => {
     if (stopped || !socket || sentClose) return;
     clearTimeout(timer);
-    const event = (record.messages[output] as CassetteWebSocketMessage | undefined) ?? (record.close?.initiator === "server" ? record.close : undefined);
+    const event = nextEvent();
     if (!event || barriers[event.afterInput] === undefined) return;
-    const delay = Math.max(0, barriers[event.afterInput] + event.delayMs - performance.now());
     timer = setTimeout(() => {
       if (stopped) return;
       try {
-        if ("data" in event) {
-          socket!.send(event.type === "text" ? event.data : new Uint8Array(Buffer.from(event.data, "base64")));
-          output++;
-          schedule();
-        } else {
-          sentClose = true;
-          closeSocket(socket!, event.code, event.reason);
+        // Flush overdue output together; one timer per message would itself
+        // add latency when catching up a continuous stream of quiet audio.
+        for (let batch = 0; batch < MAX_PENDING && !stopped; batch++) {
+          const event = nextEvent();
+          if (!event || barriers[event.afterInput] === undefined) return;
+          if (dueAt(event) > performance.now()) break;
+          if ("data" in event) {
+            const message = event.type === "text" ? event.data : new Uint8Array(Buffer.from(event.data, "base64"));
+            args.match.output?.(typeof message === "string" ? message : message.slice());
+            socket!.send(message);
+            output++;
+          } else {
+            sentClose = true;
+            closeSocket(socket!, event.code, event.reason);
+            return;
+          }
         }
+        schedule();
       } catch (error) { fail(diagnostic(`playback failed: ${(error as Error).message}`)); }
-    }, Math.min(delay, 2_147_483_647));
+    }, Math.min(Math.max(0, dueAt(event) - performance.now()), 2_147_483_647));
   };
   const session: WebSocketSession = {
     cancel() { finish(); socket?.close(1001, "replay cleanup"); },
@@ -197,11 +293,23 @@ export function replayWebSocket(args: {
     message(_ws, message) {
       if (stopped) return;
       try {
-        const actual = args.match(message);
-        if (actual === null) return;
-        const expected = record.inputs[position];
-        if (expected !== actual) throw new Error(`expected ${expected ?? "<exhausted>"}, actual ${actual}`);
-        barriers[++position] = performance.now();
+        if (args.match.candidates) {
+          let matched = false;
+          for (const actual of args.match.candidates(message)) {
+            const count = occurrence(occurrences, actual);
+            if (actual !== record.inputs[position] || count !== record.inputOccurrences![position]) continue;
+            barriers[++position] = performance.now();
+            matched = true;
+          }
+          // Unselected candidates never extend the deadline.
+          if (!matched) return;
+        } else {
+          const actual = args.match(message);
+          if (actual === null) return;
+          const expected = record.inputs[position];
+          if (expected !== actual) throw new Error(`expected ${expected ?? "<exhausted>"}, actual ${actual}`);
+          barriers[++position] = performance.now();
+        }
         armDeadline();
         schedule();
       } catch (error) {
@@ -236,7 +344,7 @@ export async function recordWebSocket(args: {
   headers: Record<string, string>;
   protocols: string[];
   request: CassetteRequest;
-  match: (message: ReplayWebSocketMessage) => string | null;
+  match: WebSocketMatcher;
   redact(value: string): string;
   secrets: { ref: string; value: string }[];
   label: string;
@@ -255,9 +363,21 @@ export async function recordWebSocket(args: {
       else callback(null, args.ip, 4);
     }) as any,
   });
-  const record: CassetteWebSocket = { request: args.request, inputs: [], messages: [] };
+  const record: CassetteWebSocket = { request: args.request, inputs: [], messages: [],
+    ...(args.match.candidates ? { inputMode: "anchors" as const, inputOccurrences: [] } : {}),
+  };
+  const occurrences = new Map<string, number>();
+  let candidate: { key: string; count: number; at: number; index: number } | undefined;
+  let candidateIndex = 0, selectedIndex = 0;
   let socket: FakeWebSocket | undefined;
   let anchor = performance.now();
+  const selectCandidate = () => {
+    if (!candidate || candidate.index === selectedIndex) return;
+    record.inputs.push(candidate.key);
+    record.inputOccurrences!.push(candidate.count);
+    anchor = candidate.at;
+    selectedIndex = candidate.index;
+  };
   let stopped = false;
   let clientClosed = false;
   let upstreamClosure: { code: number; reason: string } | undefined;
@@ -300,6 +420,8 @@ export async function recordWebSocket(args: {
       const message = binary ? new Uint8Array(bytes) : bytes.toString();
       // Redact bytes too: base64 encoding must not hide a brokered secret.
       const redacted = binary ? redactBinary(bytes, args.redact, args.secrets) : scrub(bytes.toString());
+      // Apply the same redacted output reducer that replay will see.
+      if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted)) selectCandidate();
       record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
       if (socket) socket.send(message);
       else {
@@ -314,6 +436,7 @@ export async function recordWebSocket(args: {
     if (!opened) { fail(new Error("upstream closed before handshake completed")); return; }
     try {
       if (!clientClosed) {
+        selectCandidate();
         upstreamClosure = { code, reason: reason.toString() };
         record.close = { ...timing(), initiator: "server", code, reason: scrub(reason.toString()) };
       }
@@ -348,8 +471,14 @@ export async function recordWebSocket(args: {
     message(_ws, message) {
       if (stopped) return;
       try {
-        const signature = args.match(typeof message === "string" ? message : Uint8Array.from(message));
-        if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
+        const input = typeof message === "string" ? message : Uint8Array.from(message);
+        if (args.match.candidates) {
+          const at = performance.now();
+          for (const key of args.match.candidates(input)) candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
+        } else {
+          const signature = args.match(input);
+          if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
+        }
         const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
         if (size + upstream.bufferedAmount > MAX_BUFFER) throw new Error("WebSocket upstream buffer exceeded");
         if (upstream.readyState !== WebSocket.OPEN) throw new Error("upstream is not open");
@@ -360,6 +489,7 @@ export async function recordWebSocket(args: {
       if (stopped || clientClosed) return;
       try {
         clientClosed = true;
+        selectCandidate();
         record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
         closeSocket(upstream, code, reason);
         openingTimer = setTimeout(() => finish(), 1_000);