@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

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;IAiB9B,yFAAyF;IACzF,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;IAarB,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.ts

@@ -0,0 +1,105 @@
+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 {
+		let dropped = 0;
+		for (let i = 0; i < pcm.length; i++) {
+			this.buf[this.writePos] = pcm[i];
+			this.writePos = (this.writePos + 1) % this.capacity;
+			if (this.filled < this.capacity) {
+				this.filled++;
+			} else {
+				this.readPos = (this.readPos + 1) % this.capacity;
+				dropped++;
+			}
+		}
+		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 out = new Float32Array(this.filled);
+		for (let i = 0; i < this.filled; i++) {
+			out[i] = this.buf[(this.readPos + i) % this.capacity];
+		}
+		const n = this.filled;
+		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"}

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

@@ -0,0 +1,97 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+	detectSamanthaPlaceholder,
+	SAMANTHA_PLACEHOLDER_BYTE_LENGTH,
+} from "./samantha-preset-placeholder";
+import {
+	VOICE_PRESET_MAGIC,
+	VOICE_PRESET_VERSION_V1,
+	writeVoicePresetFileV2,
+} from "./voice-preset-format";
+
+function writeLegacyV1Placeholder(): Uint8Array {
+	const blob = new Uint8Array(SAMANTHA_PLACEHOLDER_BYTE_LENGTH);
+	const view = new DataView(blob.buffer);
+	view.setUint32(0, VOICE_PRESET_MAGIC, true);
+	view.setUint32(4, VOICE_PRESET_VERSION_V1, true);
+	view.setUint32(8, 24, true);
+	view.setUint32(12, 256 * 4, true);
+	view.setUint32(16, 24 + 256 * 4, true);
+	view.setUint32(20, 4, true);
+	view.setUint32(24 + 256 * 4, 0, true);
+	return blob;
+}
+
+describe("detectSamanthaPlaceholder", () => {
+	let dir: string;
+	beforeEach(() => {
+		dir = mkdtempSync(path.join(os.tmpdir(), "samantha-placeholder-test-"));
+	});
+	afterEach(() => {
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("reports `missing` when the file does not exist", () => {
+		const out = detectSamanthaPlaceholder(path.join(dir, "absent.bin"));
+		expect(out.kind).toBe("missing");
+	});
+
+	it("reports `real-preset` for files of the wrong byte length", () => {
+		const p = path.join(dir, "tiny.bin");
+		writeFileSync(p, Buffer.alloc(64));
+		const out = detectSamanthaPlaceholder(p);
+		expect(out.kind).toBe("real-preset");
+		if (out.kind === "real-preset") {
+			expect(out.reason).toMatch(/byte-length/);
+		}
+	});
+
+	it("does not report a differently-shaped v2 zero preset as the shipped placeholder", () => {
+		// Current v2 serialization has a different byte layout than the
+		// 1052-byte I-wave placeholder staged in installed bundles.
+		const blob = writeVoicePresetFileV2({
+			embedding: new Float32Array(256), // all zeros
+			phrases: [],
+		});
+		expect(blob.byteLength).not.toBe(SAMANTHA_PLACEHOLDER_BYTE_LENGTH);
+		const p = path.join(dir, "voice-preset-default.bin");
+		writeFileSync(p, blob);
+		const out = detectSamanthaPlaceholder(p);
+		expect(out.kind).toBe("real-preset");
+	});
+
+	it("reports `placeholder` for the legacy v1 zero-fill blob staged in current bundles", () => {
+		const blob = writeLegacyV1Placeholder();
+		expect(blob.byteLength).toBe(SAMANTHA_PLACEHOLDER_BYTE_LENGTH);
+		const p = path.join(dir, "legacy-v1-placeholder.bin");
+		writeFileSync(p, blob);
+		const out = detectSamanthaPlaceholder(p);
+		expect(out.kind).toBe("placeholder");
+	});
+
+	it("reports `real-preset` when the embedding has any non-zero sample", () => {
+		const emb = new Float32Array(256);
+		emb[42] = 0.001;
+		const blob = writeVoicePresetFileV2({ embedding: emb, phrases: [] });
+		const p = path.join(dir, "almost.bin");
+		writeFileSync(p, blob);
+		const out = detectSamanthaPlaceholder(p);
+		expect(out.kind).toBe("real-preset");
+	});
+
+	it("reports `real-preset` when ref_audio_tokens or ref_text are populated", () => {
+		const blob = writeVoicePresetFileV2({
+			embedding: new Float32Array(256),
+			phrases: [],
+			refText: "Hello there.",
+		});
+		const p = path.join(dir, "with-ref.bin");
+		writeFileSync(p, blob);
+		const out = detectSamanthaPlaceholder(p);
+		expect(out.kind).toBe("real-preset");
+	});
+});

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

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import {
+	readVoicePresetFile,
+	VOICE_PRESET_HEADER_BYTES_V1,
+	VOICE_PRESET_MAGIC,
+	VOICE_PRESET_VERSION_V1,
+	VOICE_PRESET_VERSION_V2,
+	type VoicePresetFile,
+	VoicePresetFormatError,
+} from "./voice-preset-format";
+
+/** 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 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 function detectSamanthaPlaceholder(
+	presetPath: string,
+): SamanthaPlaceholderState {
+	let bytes: Uint8Array;
+	try {
+		const stat = statSync(presetPath);
+		if (!stat.isFile()) {
+			return { kind: "unreadable", reason: "path is not a regular file" };
+		}
+		bytes = new Uint8Array(readFileSync(presetPath));
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return { kind: "missing" };
+		return {
+			kind: "unreadable",
+			reason: (err as Error).message ?? String(err),
+		};
+	}
+
+	// Fast path: only the exact placeholder byte-length is a candidate.
+	if (bytes.byteLength !== SAMANTHA_PLACEHOLDER_BYTE_LENGTH) {
+		return { kind: "real-preset", reason: "byte-length mismatch" };
+	}
+
+	// Structural path: must parse as ELZ1 v1/v2 with all-zero embedding and
+	// empty ref/phrase sections.
+	if (bytes.byteLength < VOICE_PRESET_HEADER_BYTES_V1) {
+		return { kind: "real-preset", reason: "too short for v1 header" };
+	}
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (view.getUint32(0, true) !== VOICE_PRESET_MAGIC) {
+		return { kind: "real-preset", reason: "magic mismatch" };
+	}
+	const version = view.getUint32(4, true);
+	if (
+		version !== VOICE_PRESET_VERSION_V1 &&
+		version !== VOICE_PRESET_VERSION_V2
+	) {
+		return { kind: "real-preset", reason: "version mismatch" };
+	}
+
+	let parsed: VoicePresetFile;
+	try {
+		parsed = readVoicePresetFile(bytes);
+	} catch (err) {
+		// Malformed v2 file — not a placeholder we own; surface as
+		// real-preset so the loader's existing error path runs.
+		if (err instanceof VoicePresetFormatError) {
+			return { kind: "real-preset", reason: `parse failed: ${err.code}` };
+		}
+		throw err;
+	}
+
+	if (parsed.embedding.length === 0) {
+		return { kind: "real-preset", reason: "empty embedding section" };
+	}
+	if (!parsed.embedding.every((v) => v === 0)) {
+		return { kind: "real-preset", reason: "non-zero embedding sample" };
+	}
+	if (parsed.refAudioTokens.tokens.length !== 0) {
+		return { kind: "real-preset", reason: "ref_audio_tokens populated" };
+	}
+	if (parsed.refText.length !== 0) {
+		return { kind: "real-preset", reason: "ref_text populated" };
+	}
+	if (parsed.phrases.length !== 0) {
+		return { kind: "real-preset", reason: "phrase-cache seed populated" };
+	}
+
+	return { kind: "placeholder" };
+}
+
+/**
+ * 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 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 const SAMANTHA_INSTRUCT =
+	"female, american accent, young adult, moderate pitch";

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

@@ -0,0 +1,87 @@
+/**
+ * Samantha-preset on-the-fly regeneration via the fused OmniVoice FFI.
+ *
+ * Path A from W3-11: when the bundle ships the I-wave zero-fill placeholder
+ * for `cache/voice-preset-default.bin`, the runtime synthesises a real
+ * preset by encoding the bundled Samantha reference clip through the FFI's
+ * `eliza_inference_encode_reference` entrypoint and writing the resulting
+ * `ref_audio_tokens` + canonical instruct/refText into a v2 preset blob.
+ *
+ * Determinism contract:
+ *   - The reference clip bytes (24 kHz mono fp32 WAV) are pinned in the
+ *     bundle.
+ *   - The reference transcript (`SAMANTHA_REFERENCE_TRANSCRIPT`) is pinned.
+ *   - The instruct string (`SAMANTHA_INSTRUCT`) is pinned.
+ *   - The OmniVoice encode entrypoint does not consume randomness (the
+ *     HuBERT semantic + RVQ codec passes are pure functions of the input
+ *     PCM + the model weights).
+ * Therefore the produced preset bytes are reproducible byte-for-byte across
+ * boots given the same FFI library + bundle.
+ */
+/** Outcome of `ensureSamanthaPresetReady`. Distinct kinds let the caller
+ *  log the right thing at the right level without re-doing detection. */
+export type EnsureSamanthaPresetOutcome = {
+    kind: "real-preset";
+} | {
+    kind: "missing-bundle-preset";
+} | {
+    kind: "regenerated";
+    bytes: number;
+    K: number;
+    refT: number;
+} | {
+    kind: "placeholder-no-regen";
+    reason: "missing-reference-wav" | "missing-ffi-library" | "ffi-no-encode-reference" | "encode-reference-failed";
+    detail: string;
+};
+export interface RegenerateOptions {
+    bundleRoot: string;
+    /** Absolute path the regenerated preset bytes should target. The caller
+     *  performs the write — this function only produces the bytes + metadata. */
+    presetPath: string;
+    /** Override path to the Samantha reference WAV. Defaults to the bundle's
+     *  `tts/omnivoice/samantha-ref.wav`. */
+    referenceWav?: string;
+    /** Override the canonical reference transcript. Defaults to the pinned
+     *  `SAMANTHA_REFERENCE_TRANSCRIPT`. */
+    referenceText?: string;
+}
+export interface RegenerateResult {
+    bytes: Uint8Array;
+    K: number;
+    refT: number;
+    embeddingDim: number;
+}
+/**
+ * Decode a 24 kHz mono Float32 LE WAV file into a Float32Array of PCM
+ * samples. Refuses anything that is not the canonical OmniVoice reference
+ * format — encoders happily accept stereo / 16-bit / 48 kHz inputs and
+ * silently degrade, which is exactly the kind of fallback sludge AGENTS.md
+ * §3 forbids. We require the file be in the right format up front.
+ */
+export declare function decodeMonoFloat32Wav24kHz(bytes: Uint8Array): Float32Array;
+/**
+ * Run the on-the-fly regeneration. Loads the bundle's OmniVoice FFI, calls
+ * `encodeReference` against the Samantha reference clip, and serialises the
+ * result into an ELZ1 v2 preset blob. The caller writes the bytes to disk.
+ */
+export declare function regenerateSamanthaPresetFromBundle(opts: RegenerateOptions): Promise<RegenerateResult>;
+/**
+ * Pre-flight: detect a placeholder preset at the bundle's canonical path
+ * and regenerate it via OmniVoice when possible. Called by the engine's
+ * `ensureActiveBundleVoiceReady()` before the synchronous preset load.
+ *
+ * Outcomes:
+ *
+ *   - `real-preset`            — nothing to do; the file is a real preset.
+ *   - `missing-bundle-preset`  — file does not exist; the engine's existing
+ *                                error path runs (loud failure).
+ *   - `regenerated`            — preset bytes were generated and written.
+ *   - `placeholder-no-regen`   — placeholder detected but regen could not
+ *                                run (FFI missing, reference clip missing,
+ *                                etc.). Returned for the caller to log; the
+ *                                engine then falls through to the bundled
+ *                                Kokoro default voice.
+ */
+export declare function ensureSamanthaPresetReady(bundleRoot: string): Promise<EnsureSamanthaPresetOutcome>;
+//# sourceMappingURL=samantha-preset-regenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"samantha-preset-regenerator.d.ts","sourceRoot":"","sources":["samantha-preset-regenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH;yEACyE;AACzE,MAAM,MAAM,2BAA2B,GACpC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/D;IACA,IAAI,EAAE,sBAAsB,CAAC;IAC7B,MAAM,EACH,uBAAuB,GACvB,qBAAqB,GACrB,yBAAyB,GACzB,yBAAyB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CACd,CAAC;AAEL,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;iFAC6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB;4CACwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;2CACuC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACrB;AAqCD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAsEzE;AAED;;;;GAIG;AACH,wBAAsB,kCAAkC,CACvD,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAmH3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,yBAAyB,CAC9C,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,2BAA2B,CAAC,CAgEtC"}