@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.2

package/src/services/voice/real-audio-decode.test.ts

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { decodeMonoPcm16Wav, encodeMonoPcm16Wav } from "./engine-bridge";
+
+/**
+ * Real-audio coverage for the front of the single FFI pipe: the WAV → PCM
+ * decoder every transcription path feeds (`decodeMonoPcm16Wav`), exercised
+ * against the committed real WAV files rather than synthetic in-memory buffers.
+ *
+ * Two real corpora:
+ *   1. `native/verify/asr_bench_fixtures/non_publish_structure_5utt/` — five
+ *      committed mono 16 kHz PCM16 WAVs (deterministic tones, NOT speech — see
+ *      the corpus manifest; valid for decode/codec validation, NOT for WER).
+ *   2. `native/omnivoice.cpp/examples/freeman.wav` — a real 22.05 kHz speech
+ *      recording. Lives in a git submodule, so the block is skipped when the
+ *      submodule isn't checked out.
+ */
+
+const FIXTURE_DIR = fileURLToPath(
+	new URL(
+		"../../../native/verify/asr_bench_fixtures/non_publish_structure_5utt/",
+		import.meta.url,
+	),
+);
+
+interface FixtureManifest {
+	realRecorded: boolean;
+	files: Array<{
+		id: string;
+		reference: string;
+		wav: string;
+		txt: string;
+		sampleRateHz: number;
+	}>;
+}
+
+const manifest = JSON.parse(
+	readFileSync(join(FIXTURE_DIR, "manifest.json"), "utf8"),
+) as FixtureManifest;
+
+/**
+ * Every decoded sample must be a finite mono amplitude in [-1, 1]. Scan in a
+ * plain loop and assert the AGGREGATE once — a per-sample `expect()` over a
+ * multi-second clip (freeman.wav is ~380k samples) is pathologically slow and
+ * trips the test timeout under load.
+ */
+function assertInRangePcm(pcm: Float32Array): void {
+	expect(pcm.length).toBeGreaterThan(0);
+	let allFinite = true;
+	let maxAbs = 0;
+	for (let i = 0; i < pcm.length; i++) {
+		const s = pcm[i] ?? Number.NaN;
+		if (!Number.isFinite(s)) {
+			allFinite = false;
+			break;
+		}
+		const abs = Math.abs(s);
+		if (abs > maxAbs) maxAbs = abs;
+	}
+	expect(allFinite).toBe(true);
+	expect(maxAbs).toBeLessThanOrEqual(1);
+}
+
+describe("decodeMonoPcm16Wav — committed fixture corpus (real WAV files)", () => {
+	it("decodes every fixture to in-range mono PCM at the manifest sample rate", () => {
+		expect(manifest.files.length).toBeGreaterThanOrEqual(5);
+		for (const f of manifest.files) {
+			const bytes = new Uint8Array(readFileSync(join(FIXTURE_DIR, f.wav)));
+			const { pcm, sampleRate } = decodeMonoPcm16Wav(bytes);
+
+			expect(sampleRate).toBe(f.sampleRateHz);
+			assertInRangePcm(pcm);
+
+			const durationMs = (1000 * pcm.length) / sampleRate;
+			expect(durationMs).toBeGreaterThan(0);
+			expect(Number.isFinite(durationMs)).toBe(true);
+
+			// Corpus integrity: the sidecar .txt matches the manifest reference
+			// (these are the references a real-speech replacement corpus must hit).
+			const txt = readFileSync(join(FIXTURE_DIR, f.txt), "utf8").trim();
+			expect(txt).toBe(f.reference);
+		}
+	});
+
+	it("round-trips decode → encode → decode losslessly (PCM16 codec)", () => {
+		const first = manifest.files[0];
+		expect(first).toBeDefined();
+		const bytes = new Uint8Array(
+			readFileSync(
+				join(FIXTURE_DIR, (first as FixtureManifest["files"][0]).wav),
+			),
+		);
+		const a = decodeMonoPcm16Wav(bytes);
+		const reencoded = encodeMonoPcm16Wav(a.pcm, a.sampleRate);
+		const b = decodeMonoPcm16Wav(reencoded);
+
+		expect(b.sampleRate).toBe(a.sampleRate);
+		expect(b.pcm.length).toBe(a.pcm.length);
+		// PCM16 → float → PCM16 is exact (the float values are k/0x8000).
+		for (let i = 0; i < a.pcm.length; i++) {
+			expect(b.pcm[i]).toBeCloseTo(a.pcm[i] ?? 0, 6);
+		}
+	});
+
+	it("documents that the fixture corpus is non-speech (not WER evidence)", () => {
+		// Guards against anyone treating these tones as ASR ground truth.
+		expect(manifest.realRecorded).toBe(false);
+	});
+});
+
+const FREEMAN_WAV = fileURLToPath(
+	new URL(
+		"../../../native/omnivoice.cpp/examples/freeman.wav",
+		import.meta.url,
+	),
+);
+const hasFreeman = existsSync(FREEMAN_WAV);
+const describeFreeman = hasFreeman ? describe : describe.skip;
+
+describeFreeman(
+	"decodeMonoPcm16Wav — freeman.wav (real 22.05 kHz speech)",
+	() => {
+		it("decodes to several seconds of bipolar in-range speech PCM", () => {
+			const bytes = new Uint8Array(readFileSync(FREEMAN_WAV));
+			const { pcm, sampleRate } = decodeMonoPcm16Wav(bytes);
+
+			expect(sampleRate).toBe(22_050);
+			assertInRangePcm(pcm);
+
+			// Real speech is bipolar, not silence or a DC tone.
+			let min = Number.POSITIVE_INFINITY;
+			let max = Number.NEGATIVE_INFINITY;
+			for (let i = 0; i < pcm.length; i++) {
+				const s = pcm[i] ?? 0;
+				if (s < min) min = s;
+				if (s > max) max = s;
+			}
+			expect(min).toBeLessThan(0);
+			expect(max).toBeGreaterThan(0);
+
+			const durationSec = pcm.length / sampleRate;
+			expect(durationSec).toBeGreaterThan(1);
+			expect(durationSec).toBeLessThan(60);
+		});
+	},
+);

package/src/services/voice/ring-buffer.d.ts

@@ -0,0 +1,40 @@
+import type { AudioSink } from "./types";
+export interface PcmRingBufferOptions {
+    /**
+     * Fired when the buffer is full and a write overwrites unread samples.
+     * Reports the count of dropped samples in this write call. Schedulers
+     * should use this signal to apply backpressure upstream — silent
+     * overwrites produce audible glitches.
+     */
+    onOverflow?: (droppedSamples: number) => void;
+}
+export declare class PcmRingBuffer {
+    private readonly capacity;
+    private readonly sampleRate;
+    private readonly sink;
+    private readonly buf;
+    private readPos;
+    private writePos;
+    private filled;
+    private readonly onOverflow?;
+    constructor(capacity: number, sampleRate: number, sink: AudioSink, options?: PcmRingBufferOptions);
+    write(pcm: Float32Array): void;
+    /** Fill ratio in [0, 1]. Schedulers can throttle TTS dispatches as this approaches 1. */
+    pressure(): number;
+    flushToSink(): number;
+    drain(): void;
+    size(): number;
+    capacityHint(): number;
+}
+export declare class InMemoryAudioSink implements AudioSink {
+    readonly chunks: Array<{
+        pcm: Float32Array;
+        sampleRate: number;
+    }>;
+    private buffered;
+    write(pcm: Float32Array, sampleRate: number): void;
+    drain(): void;
+    bufferedSamples(): number;
+    totalWritten(): number;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/src/services/voice/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["ring-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED,qBAAa,aAAa;IAQxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IATtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAmC;gBAG7C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,EAChC,OAAO,GAAE,oBAAyB;IASnC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAkC9B,yFAAyF;IACzF,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;IAcrB,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,MAAM;IAId,YAAY,IAAI,MAAM;CAGtB;AAED,qBAAa,iBAAkB,YAAW,SAAS;IAClD,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAM;IACvE,OAAO,CAAC,QAAQ,CAAK;IAErB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAKlD,KAAK,IAAI,IAAI;IAIb,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM;CAKtB"}

package/src/services/voice/ring-buffer.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import { InMemoryAudioSink, PcmRingBuffer } from "./ring-buffer";
+
+function f32(...xs: number[]): Float32Array {
+	return Float32Array.from(xs);
+}
+
+/** Concatenate everything an InMemoryAudioSink received, in order. */
+function sinkData(sink: InMemoryAudioSink): number[] {
+	const out: number[] = [];
+	for (const c of sink.chunks) out.push(...c.pcm);
+	return out;
+}
+
+describe("PcmRingBuffer (bulk-copy)", () => {
+	it("writes then flushes in FIFO order", () => {
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(8, 16000, sink);
+		rb.write(f32(1, 2, 3));
+		rb.write(f32(4, 5));
+		expect(rb.size()).toBe(5);
+		expect(rb.flushToSink()).toBe(5);
+		expect(sinkData(sink)).toEqual([1, 2, 3, 4, 5]);
+		expect(rb.size()).toBe(0);
+	});
+
+	it("handles a write that wraps the write cursor", () => {
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(4, 16000, sink);
+		rb.write(f32(1, 2, 3)); // writePos=3
+		expect(rb.flushToSink()).toBe(3); // readPos=writePos=3
+		rb.write(f32(4, 5, 6)); // wraps: positions 3,0,1
+		expect(rb.flushToSink()).toBe(3);
+		expect(sinkData(sink)).toEqual([1, 2, 3, 4, 5, 6]);
+	});
+
+	it("drops oldest samples on overflow and reports the count", () => {
+		const sink = new InMemoryAudioSink();
+		const dropped: number[] = [];
+		const rb = new PcmRingBuffer(4, 16000, sink, {
+			onOverflow: (n) => dropped.push(n),
+		});
+		rb.write(f32(1, 2, 3)); // filled=3
+		rb.write(f32(4, 5, 6)); // filled would be 6 → drop 2 oldest (1,2)
+		expect(dropped).toEqual([2]);
+		expect(rb.size()).toBe(4);
+		expect(rb.flushToSink()).toBe(4);
+		expect(sinkData(sink)).toEqual([3, 4, 5, 6]);
+	});
+
+	it("keeps only the last `capacity` samples when one write exceeds capacity", () => {
+		const sink = new InMemoryAudioSink();
+		const dropped: number[] = [];
+		const rb = new PcmRingBuffer(4, 16000, sink, {
+			onOverflow: (n) => dropped.push(n),
+		});
+		rb.write(f32(1, 2, 3, 4, 5, 6, 7)); // 7 samples into cap-4 → keep 4,5,6,7
+		expect(dropped).toEqual([3]);
+		expect(rb.size()).toBe(4);
+		rb.flushToSink();
+		expect(sinkData(sink)).toEqual([4, 5, 6, 7]);
+	});
+
+	it("exact-capacity write fills without dropping", () => {
+		const sink = new InMemoryAudioSink();
+		const dropped: number[] = [];
+		const rb = new PcmRingBuffer(4, 16000, sink, {
+			onOverflow: (n) => dropped.push(n),
+		});
+		rb.write(f32(1, 2, 3, 4));
+		expect(dropped).toEqual([]);
+		expect(rb.size()).toBe(4);
+		rb.flushToSink();
+		expect(sinkData(sink)).toEqual([1, 2, 3, 4]);
+	});
+
+	it("partial overflow when already partly filled, with wrap", () => {
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(4, 16000, sink);
+		rb.write(f32(1, 2)); // writePos=2, filled=2
+		rb.write(f32(3, 4, 5)); // 3→pos2, 4→pos3, 5→pos0 (overwrites 1); drop 1
+		// logical order now: 2,3,4,5
+		expect(rb.size()).toBe(4);
+		rb.flushToSink();
+		expect(sinkData(sink)).toEqual([2, 3, 4, 5]);
+	});
+
+	it("pressure reflects fill ratio", () => {
+		const rb = new PcmRingBuffer(10, 16000, new InMemoryAudioSink());
+		expect(rb.pressure()).toBe(0);
+		rb.write(f32(1, 2, 3, 4, 5));
+		expect(rb.pressure()).toBeCloseTo(0.5);
+	});
+
+	it("drain clears without writing to the sink", () => {
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(4, 16000, sink);
+		rb.write(f32(1, 2, 3));
+		rb.drain();
+		expect(rb.size()).toBe(0);
+		expect(sinkData(sink)).toEqual([]);
+	});
+
+	it("empty write is a no-op", () => {
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(4, 16000, sink);
+		rb.write(new Float32Array(0));
+		expect(rb.size()).toBe(0);
+		expect(rb.flushToSink()).toBe(0);
+	});
+
+	it("matches the reference per-sample model over a randomized-ish sequence", () => {
+		// Reference oracle implemented straightforwardly; compare logical contents.
+		const cap = 5;
+		const sink = new InMemoryAudioSink();
+		const rb = new PcmRingBuffer(cap, 16000, sink);
+		const ref: number[] = [];
+		const writes = [[1, 2], [3, 4, 5, 6], [7], [8, 9, 10, 11, 12, 13]];
+		const value = 0;
+		for (const w of writes) {
+			void value;
+			rb.write(Float32Array.from(w));
+			ref.push(...w);
+			while (ref.length > cap) ref.shift();
+		}
+		rb.flushToSink();
+		expect(sinkData(sink)).toEqual(ref);
+	});
+});

package/src/services/voice/ring-buffer.ts

@@ -0,0 +1,123 @@
+import type { AudioSink } from "./types";
+
+export interface PcmRingBufferOptions {
+	/**
+	 * Fired when the buffer is full and a write overwrites unread samples.
+	 * Reports the count of dropped samples in this write call. Schedulers
+	 * should use this signal to apply backpressure upstream — silent
+	 * overwrites produce audible glitches.
+	 */
+	onOverflow?: (droppedSamples: number) => void;
+}
+
+export class PcmRingBuffer {
+	private readonly buf: Float32Array;
+	private readPos = 0;
+	private writePos = 0;
+	private filled = 0;
+	private readonly onOverflow?: (droppedSamples: number) => void;
+
+	constructor(
+		private readonly capacity: number,
+		private readonly sampleRate: number,
+		private readonly sink: AudioSink,
+		options: PcmRingBufferOptions = {},
+	) {
+		if (capacity <= 0) {
+			throw new Error("PcmRingBuffer: capacity must be positive");
+		}
+		this.buf = new Float32Array(capacity);
+		this.onOverflow = options.onOverflow;
+	}
+
+	write(pcm: Float32Array): void {
+		const n = pcm.length;
+		if (n === 0) return;
+		// Samples lost to overwrite: everything past capacity once we account for
+		// what's already buffered. Matches the per-sample loop's drop accounting.
+		const dropped = Math.max(0, this.filled + n - this.capacity);
+
+		if (n >= this.capacity) {
+			// The incoming chunk alone fills (or overfills) the ring — only its last
+			// `capacity` samples survive. Bulk-copy them and reset to a full buffer.
+			this.buf.set(pcm.subarray(n - this.capacity, n), 0);
+			this.readPos = 0;
+			this.writePos = 0;
+			this.filled = this.capacity;
+		} else {
+			// Up to two contiguous bulk copies (one before the wrap, one after).
+			const firstSpan = Math.min(n, this.capacity - this.writePos);
+			this.buf.set(pcm.subarray(0, firstSpan), this.writePos);
+			if (n > firstSpan) this.buf.set(pcm.subarray(firstSpan, n), 0);
+			this.writePos = (this.writePos + n) % this.capacity;
+			if (dropped > 0) {
+				// Buffer overran: the read cursor chases the write cursor.
+				this.readPos = (this.readPos + dropped) % this.capacity;
+				this.filled = this.capacity;
+			} else {
+				this.filled += n;
+			}
+		}
+
+		if (dropped > 0 && this.onOverflow) {
+			this.onOverflow(dropped);
+		}
+	}
+
+	/** Fill ratio in [0, 1]. Schedulers can throttle TTS dispatches as this approaches 1. */
+	pressure(): number {
+		return this.filled / this.capacity;
+	}
+
+	flushToSink(): number {
+		if (this.filled === 0) return 0;
+		const n = this.filled;
+		const out = new Float32Array(n);
+		// Read `n` samples from readPos with at most one wrap — two bulk copies.
+		const firstSpan = Math.min(n, this.capacity - this.readPos);
+		out.set(this.buf.subarray(this.readPos, this.readPos + firstSpan), 0);
+		if (n > firstSpan) out.set(this.buf.subarray(0, n - firstSpan), firstSpan);
+		this.readPos = this.writePos;
+		this.filled = 0;
+		this.sink.write(out, this.sampleRate);
+		return n;
+	}
+
+	drain(): void {
+		this.readPos = this.writePos;
+		this.filled = 0;
+		this.sink.drain();
+	}
+
+	size(): number {
+		return this.filled;
+	}
+
+	capacityHint(): number {
+		return this.capacity;
+	}
+}
+
+export class InMemoryAudioSink implements AudioSink {
+	readonly chunks: Array<{ pcm: Float32Array; sampleRate: number }> = [];
+	private buffered = 0;
+
+	write(pcm: Float32Array, sampleRate: number): void {
+		this.chunks.push({ pcm, sampleRate });
+		this.buffered += pcm.length;
+	}
+
+	drain(): void {
+		this.buffered = 0;
+	}
+
+	bufferedSamples(): number {
+		return this.buffered;
+	}
+
+	totalWritten(): number {
+		let n = 0;
+		for (const c of this.chunks) n += c.pcm.length;
+		return n;
+	}
+}

package/src/services/voice/rollback-queue.d.ts

@@ -0,0 +1,24 @@
+import type { Phrase, RejectedTokenRange } from "./types";
+type PhraseState = "queued" | "synthesizing" | "ringbuffered" | "played";
+export interface RollbackEvent {
+    phraseId: number;
+    reason: "rejected-tokens";
+    rejectedRange: RejectedTokenRange;
+}
+export declare class RollbackQueue {
+    private readonly tracked;
+    track(phrase: Phrase): void;
+    markSynthesizing(phraseId: number): void;
+    markRingBuffered(phraseId: number): void;
+    markPlayed(phraseId: number): void;
+    drop(phraseId: number): void;
+    onRejected(range: RejectedTokenRange): RollbackEvent[];
+    snapshot(): ReadonlyArray<{
+        phrase: Phrase;
+        state: PhraseState;
+    }>;
+    private requireEntry;
+    private overlaps;
+}
+export {};
+//# sourceMappingURL=rollback-queue.d.ts.map

package/src/services/voice/rollback-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-queue.d.ts","sourceRoot":"","sources":["rollback-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE1D,KAAK,WAAW,GAAG,QAAQ,GAAG,cAAc,GAAG,cAAc,GAAG,QAAQ,CAAC;AAOzE,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,aAAa,EAAE,kBAAkB,CAAC;CAClC;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKxC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKxC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKlC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI5B,UAAU,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,EAAE;IAetD,QAAQ,IAAI,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,CAAC;IAIjE,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,QAAQ;CAKhB"}

package/src/services/voice/rollback-queue.ts

@@ -0,0 +1,74 @@
+import type { Phrase, RejectedTokenRange } from "./types";
+
+type PhraseState = "queued" | "synthesizing" | "ringbuffered" | "played";
+
+interface TrackedPhrase {
+	phrase: Phrase;
+	state: PhraseState;
+}
+
+export interface RollbackEvent {
+	phraseId: number;
+	reason: "rejected-tokens";
+	rejectedRange: RejectedTokenRange;
+}
+
+export class RollbackQueue {
+	private readonly tracked = new Map<number, TrackedPhrase>();
+
+	track(phrase: Phrase): void {
+		this.tracked.set(phrase.id, { phrase, state: "queued" });
+	}
+
+	markSynthesizing(phraseId: number): void {
+		const entry = this.requireEntry(phraseId);
+		entry.state = "synthesizing";
+	}
+
+	markRingBuffered(phraseId: number): void {
+		const entry = this.requireEntry(phraseId);
+		entry.state = "ringbuffered";
+	}
+
+	markPlayed(phraseId: number): void {
+		const entry = this.requireEntry(phraseId);
+		entry.state = "played";
+	}
+
+	drop(phraseId: number): void {
+		this.tracked.delete(phraseId);
+	}
+
+	onRejected(range: RejectedTokenRange): RollbackEvent[] {
+		const events: RollbackEvent[] = [];
+		for (const entry of this.tracked.values()) {
+			if (entry.state === "played") continue;
+			if (this.overlaps(entry.phrase, range)) {
+				events.push({
+					phraseId: entry.phrase.id,
+					reason: "rejected-tokens",
+					rejectedRange: range,
+				});
+			}
+		}
+		return events;
+	}
+
+	snapshot(): ReadonlyArray<{ phrase: Phrase; state: PhraseState }> {
+		return Array.from(this.tracked.values()).map((e) => ({ ...e }));
+	}
+
+	private requireEntry(phraseId: number): TrackedPhrase {
+		const entry = this.tracked.get(phraseId);
+		if (!entry) {
+			throw new Error(`RollbackQueue: unknown phraseId ${phraseId}`);
+		}
+		return entry;
+	}
+
+	private overlaps(phrase: Phrase, range: RejectedTokenRange): boolean {
+		return (
+			phrase.toIndex >= range.fromIndex && phrase.fromIndex <= range.toIndex
+		);
+	}
+}

package/src/services/voice/samantha-preset-placeholder.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Samantha-preset placeholder detection + on-the-fly regeneration.
+ *
+ * Background: the canonical default voice (Samantha, `af_same`) ships with
+ * the Eliza-1 bundle as `cache/voice-preset-default.bin` (ELZ1 format).
+ * The first I-wave shipped a 1052-byte zero-filled placeholder before the
+ * real preset bytes were produced — the runtime treats this placeholder as
+ * "not yet generated" and synthesises a fresh preset on first boot via the
+ * fused OmniVoice TTS (Path A).
+ *
+ * The detection rule is intentionally narrow: only an ELZ1 v1/v2 file whose
+ * (a) speaker embedding is exactly zero AND (b) ref_audio_tokens / ref_text
+ * are empty AND (c) phrase-cache seed is empty counts as a placeholder. Any
+ * file that has even one non-zero region is considered real and is left
+ * alone — the runtime never silently overwrites operator-supplied presets.
+ *
+ * The fallback chain executed by `EngineVoiceBridge.start()`:
+ *
+ *   1. If `cache/voice-preset-default.bin` is missing → throw (existing
+ *      behaviour, the bundle is malformed).
+ *   2. If the file exists and is NOT a placeholder → load it as-is.
+ *   3. If it IS a placeholder AND the OmniVoice reference-encode FFI is
+ *      available → regenerate the preset using the bundled Samantha
+ *      reference clip + transcript, write the new bytes back to disk,
+ *      then load.
+ *   4. If it IS a placeholder AND OmniVoice reference-encode is unavailable
+ *      → log a loud warning and fall through to the bundled Kokoro default
+ *      voice (`kokoro.defaultVoiceId`) by re-pointing the discovery layer.
+ */
+/** The exact byte-length the I-wave placeholder shipped at. Used as a fast
+ *  pre-check before the more expensive structural parse — files of any
+ *  other size cannot be the placeholder. */
+export declare const SAMANTHA_PLACEHOLDER_BYTE_LENGTH = 1052;
+/** Reasons `detectSamanthaPlaceholder` returns. Each is structurally
+ *  distinct so the caller can branch without re-parsing. */
+export type SamanthaPlaceholderState = {
+    kind: "missing";
+} | {
+    kind: "real-preset";
+    reason: string;
+} | {
+    kind: "placeholder";
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+/**
+ * Inspect `presetPath` and report whether it is the I-wave zero-fill
+ * placeholder, a real preset, missing, or unreadable. Pure I/O — no
+ * mutation of the file.
+ */
+export declare function detectSamanthaPlaceholder(presetPath: string): SamanthaPlaceholderState;
+/**
+ * The text the on-the-fly regeneration uses as the Samantha reference
+ * transcript. Stable across versions so the produced preset is
+ * deterministic — pinning the prompt is part of the cacheability contract
+ * (same inputs -> same output bytes for byte-for-byte comparison).
+ */
+export declare const SAMANTHA_REFERENCE_TRANSCRIPT = "Hi, I'm Samantha. It's nice to finally talk to you about something real.";
+/**
+ * The closed-vocabulary VoiceDesign instruct string baked into the
+ * regenerated Samantha preset. Mirrors the publish-time freeze CLI's
+ * settings so the runtime regen and a future operator-built preset land on
+ * the same surface. Pinned for deterministic regeneration.
+ */
+export declare const SAMANTHA_INSTRUCT = "female, american accent, young adult, moderate pitch";
+//# sourceMappingURL=samantha-preset-placeholder.d.ts.map

package/src/services/voice/samantha-preset-placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"samantha-preset-placeholder.d.ts","sourceRoot":"","sources":["samantha-preset-placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAaH;;4CAE4C;AAC5C,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD;4DAC4D;AAC5D,MAAM,MAAM,wBAAwB,GACjC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,GAChB,wBAAwB,CAoE1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,6EACiC,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,yDACyB,CAAC"}