@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/services/local-inference/voice/rollback-queue.js

@@ -0,0 +1,49 @@
+export class RollbackQueue {
+    tracked = new Map();
+    track(phrase) {
+        this.tracked.set(phrase.id, { phrase, state: "queued" });
+    }
+    markSynthesizing(phraseId) {
+        const entry = this.requireEntry(phraseId);
+        entry.state = "synthesizing";
+    }
+    markRingBuffered(phraseId) {
+        const entry = this.requireEntry(phraseId);
+        entry.state = "ringbuffered";
+    }
+    markPlayed(phraseId) {
+        const entry = this.requireEntry(phraseId);
+        entry.state = "played";
+    }
+    drop(phraseId) {
+        this.tracked.delete(phraseId);
+    }
+    onRejected(range) {
+        const events = [];
+        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() {
+        return Array.from(this.tracked.values()).map((e) => ({ ...e }));
+    }
+    requireEntry(phraseId) {
+        const entry = this.tracked.get(phraseId);
+        if (!entry) {
+            throw new Error(`RollbackQueue: unknown phraseId ${phraseId}`);
+        }
+        return entry;
+    }
+    overlaps(phrase, range) {
+        return phrase.toIndex >= range.fromIndex && phrase.fromIndex <= range.toIndex;
+    }
+}

package/services/local-inference/voice/scheduler.d.ts

@@ -0,0 +1,47 @@
+import { BargeInController } from "./barge-in";
+import type { PhonemeTokenizer } from "./phoneme-tokenizer";
+import { PhraseCache } from "./phrase-cache";
+import { PhraseChunker } from "./phrase-chunker";
+import { PcmRingBuffer } from "./ring-buffer";
+import { RollbackQueue } from "./rollback-queue";
+import type { AudioChunk, AudioSink, OmniVoiceBackend, Phrase, RejectedTokenRange, SchedulerConfig, SpeakerPreset, TextToken } from "./types";
+export interface SchedulerEvents {
+    onPhrase?(phrase: Phrase): void;
+    onRollback?(phraseId: number, range: RejectedTokenRange): void;
+    onAudio?(chunk: AudioChunk): void;
+    onCancel?(): void;
+}
+export interface SchedulerDeps {
+    backend: OmniVoiceBackend;
+    sink?: AudioSink;
+    phraseCache?: PhraseCache;
+    /** Optional. Required only when `config.chunkerConfig.chunkOn ===
+     *  'phoneme-stream'`. Pass a real tokenizer in production; tests may
+     *  pass `CharacterPhonemeStub`. */
+    phonemeTokenizer?: PhonemeTokenizer;
+}
+export declare class VoiceScheduler {
+    readonly chunker: PhraseChunker;
+    readonly rollback: RollbackQueue;
+    readonly bargeIn: BargeInController;
+    readonly ringBuffer: PcmRingBuffer;
+    readonly sink: AudioSink;
+    readonly preset: SpeakerPreset;
+    private readonly backend;
+    private readonly phraseCache;
+    private readonly events;
+    private readonly inFlight;
+    private readonly maxInFlight;
+    private kernelTicks;
+    constructor(config: SchedulerConfig, deps: SchedulerDeps, events?: SchedulerEvents);
+    accept(token: TextToken, acceptedAt?: number): Promise<void>;
+    reject(range: RejectedTokenRange): Promise<void>;
+    flushPending(): Promise<void>;
+    waitIdle(): Promise<void>;
+    tickKernel(): void;
+    kernelTickCount(): number;
+    private dispatchPhrase;
+    private commitAudio;
+    private handleBargeIn;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/services/local-inference/voice/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAqB,aAAa,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,SAAS,EACV,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;uCAEmC;IACnC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAUD,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,gBAAuB;IACxC,QAAQ,CAAC,OAAO,oBAA2B;IAC3C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,WAAW,CAAK;gBAGtB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,eAAoB;IAyBxB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,SAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,UAAU,IAAI,IAAI;IAIlB,eAAe,IAAI,MAAM;YAIX,cAAc;IA8C5B,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,aAAa;CAQtB"}

package/services/local-inference/voice/scheduler.js

@@ -0,0 +1,123 @@
+import { BargeInController } from "./barge-in";
+import { PhraseCache } from "./phrase-cache";
+import { PhraseChunker } from "./phrase-chunker";
+import { InMemoryAudioSink, PcmRingBuffer } from "./ring-buffer";
+import { RollbackQueue } from "./rollback-queue";
+const DEFAULT_MAX_IN_FLIGHT_PHRASES = 4;
+export class VoiceScheduler {
+    chunker;
+    rollback = new RollbackQueue();
+    bargeIn = new BargeInController();
+    ringBuffer;
+    sink;
+    preset;
+    backend;
+    phraseCache;
+    events;
+    inFlight = new Map();
+    maxInFlight;
+    kernelTicks = 0;
+    constructor(config, deps, events = {}) {
+        this.chunker = new PhraseChunker(config.chunkerConfig, deps.phonemeTokenizer ?? null);
+        this.preset = config.preset;
+        this.backend = deps.backend;
+        this.phraseCache = deps.phraseCache ?? new PhraseCache();
+        this.sink = deps.sink ?? new InMemoryAudioSink();
+        this.ringBuffer = new PcmRingBuffer(config.ringBufferCapacity, config.sampleRate, this.sink);
+        this.events = events;
+        this.maxInFlight = Math.max(1, config.maxInFlightPhrases ?? DEFAULT_MAX_IN_FLIGHT_PHRASES);
+        this.bargeIn.attach({
+            onCancel: () => this.handleBargeIn(),
+        });
+    }
+    async accept(token, acceptedAt = Date.now()) {
+        const acc = { ...token, acceptedAt };
+        const phrase = this.chunker.push(acc);
+        if (phrase) {
+            await this.dispatchPhrase(phrase);
+        }
+    }
+    async reject(range) {
+        const events = this.rollback.onRejected(range);
+        for (const ev of events) {
+            const inflight = this.inFlight.get(ev.phraseId);
+            if (inflight) {
+                inflight.cancelSignal.cancelled = true;
+            }
+            this.rollback.drop(ev.phraseId);
+            this.events.onRollback?.(ev.phraseId, range);
+        }
+    }
+    async flushPending() {
+        const tail = this.chunker.flushPending();
+        if (tail) {
+            await this.dispatchPhrase(tail);
+        }
+    }
+    async waitIdle() {
+        const all = Array.from(this.inFlight.values()).map((i) => i.done);
+        await Promise.all(all);
+    }
+    tickKernel() {
+        this.kernelTicks++;
+    }
+    kernelTickCount() {
+        return this.kernelTicks;
+    }
+    async dispatchPhrase(phrase) {
+        this.rollback.track(phrase);
+        this.events.onPhrase?.(phrase);
+        const cached = this.phraseCache.get(phrase.text);
+        if (cached) {
+            const chunk = {
+                phraseId: phrase.id,
+                fromIndex: phrase.fromIndex,
+                toIndex: phrase.toIndex,
+                pcm: cached.pcm,
+                sampleRate: cached.sampleRate,
+            };
+            this.commitAudio(chunk);
+            return;
+        }
+        if (this.inFlight.size >= this.maxInFlight) {
+            const oldest = this.inFlight.values().next().value;
+            if (oldest) {
+                await oldest.done;
+            }
+        }
+        const cancelSignal = { cancelled: false };
+        const done = (async () => {
+            this.rollback.markSynthesizing(phrase.id);
+            const chunk = await this.backend.synthesize({
+                phrase,
+                preset: this.preset,
+                cancelSignal,
+                onKernelTick: () => this.tickKernel(),
+            });
+            this.inFlight.delete(phrase.id);
+            if (cancelSignal.cancelled) {
+                return;
+            }
+            if (!this.rollback.snapshot().some((e) => e.phrase.id === phrase.id)) {
+                return;
+            }
+            this.commitAudio(chunk);
+        })();
+        this.inFlight.set(phrase.id, { phrase, cancelSignal, done });
+    }
+    commitAudio(chunk) {
+        this.rollback.markRingBuffered(chunk.phraseId);
+        this.ringBuffer.write(chunk.pcm);
+        this.ringBuffer.flushToSink();
+        this.rollback.markPlayed(chunk.phraseId);
+        this.events.onAudio?.(chunk);
+    }
+    handleBargeIn() {
+        this.ringBuffer.drain();
+        this.chunker.reset();
+        for (const inflight of this.inFlight.values()) {
+            inflight.cancelSignal.cancelled = true;
+        }
+        this.events.onCancel?.();
+    }
+}

package/services/local-inference/voice/shared-resources.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Cross-cut resource sharing between the text + voice surfaces of a
+ * single Eliza-1 bundle.
+ *
+ * Per `packages/inference/AGENTS.md` §4 ("shared KV cache scheduling,
+ * not shared KV memory" + "one process, one llama.cpp build, one GGML
+ * pin"), text and voice MUST share:
+ *   - the tokenizer (Eliza-1/OmniVoice share a vocabulary in this lineage),
+ *   - the mmap regions for weights (deduplicated by absolute path),
+ *   - the kernel set (same shipped llama.cpp library after fusion),
+ *   - the scheduler queue (one queue, prioritised),
+ *   - the DFlash drafter (always wired, see AGENTS.md §3 #4).
+ *
+ * What they do NOT share:
+ *   - KV cache memory (different layer counts, different head configs,
+ *     different quantizations — separate caches, shared scheduler).
+ *
+ * This module owns reference counts on each shared resource and is the
+ * single arbiter of when an mmap region can be released back to the OS
+ * via the `madvise` path documented in `lifecycle.ts`. It does NOT do
+ * any I/O itself — the actual mmap + page-eviction syscalls live behind
+ * the `MmapRegionHandle` interface so platform-specific bindings can
+ * implement them.
+ */
+/** Minimal structural logger — keeps this module free of upstream deps. */
+interface Logger {
+    debug?(message: string): void;
+    warn?(message: string): void;
+}
+/**
+ * Anything ref-counted by the registry implements this. The caller of
+ * `release()` MUST guarantee that no further reads happen on the
+ * underlying resource — for mmap regions that means no kernel call has
+ * a pointer into the freed range.
+ */
+export interface RefCountedResource {
+    readonly id: string;
+    /** Released for real when the last ref drops. Idempotent. */
+    release(): Promise<void>;
+}
+/**
+ * mmap region handle. The fused omnivoice/llama.cpp build owns the real
+ * mmap call (it happens inside the FFI) — this interface is the JS-side
+ * proxy for it, so the lifecycle code can request page eviction without
+ * binding to a specific backend.
+ */
+export interface MmapRegionHandle extends RefCountedResource {
+    /** Absolute path of the file backing the mmap region. */
+    readonly path: string;
+    /** Byte size of the mapped region. */
+    readonly sizeBytes: number;
+    /**
+     * Hint the kernel that the pages are no longer needed. Backed by:
+     *   - POSIX (Linux/Android/macOS-bg): `madvise(addr, len, MADV_DONTNEED)`
+     *   - macOS (foreground / iOS):        `madvise(addr, len, MADV_FREE_REUSABLE)`
+     *   - Windows:                         `VirtualUnlock` + `OfferVirtualMemory`
+     *
+     * On the JS side this is a no-op until the FFI binding ships. The
+     * lifecycle test mocks this to assert the call happened.
+     */
+    evictPages(): Promise<void>;
+}
+/** Minimal tokenizer surface text + voice both consume. */
+export interface SharedTokenizer extends RefCountedResource {
+    readonly vocabSize: number;
+}
+/**
+ * Kernel set descriptor. The actual kernels are inside the fused
+ * llama.cpp build; this is the metadata the runtime reads at startup
+ * (AGENTS.md §3 #5: "the runtime MUST log the kernel set on startup").
+ */
+export interface KernelSet extends RefCountedResource {
+    readonly kernels: ReadonlyArray<string>;
+}
+/** Scheduler graph slot. One per active engine, refcounted by surface. */
+export interface SchedulerSlot extends RefCountedResource {
+    /** Surface (text/voice) currently holding a ref. */
+    surfaces(): ReadonlyArray<"text" | "voice">;
+}
+/** DFlash drafter is shared between text-only and voice modes (AGENTS.md §4). */
+export interface DflashDrafterHandle extends RefCountedResource {
+    readonly drafterModelId: string;
+}
+/**
+ * Owns the shared resources for one engine. Voice + text both `acquire`
+ * and `release` against the same registry; the registry only releases
+ * the underlying resource when refcount hits zero.
+ *
+ * Thread-safety: all methods run on the single Node event loop; no
+ * locks needed. Promises returned from `release()` MUST be awaited so
+ * the lifecycle state machine can observe completion.
+ */
+export declare class SharedResourceRegistry {
+    private readonly entries;
+    private readonly log?;
+    constructor(opts?: {
+        logger?: Logger;
+    });
+    /**
+     * Register a resource if absent, increment refcount otherwise. Returns
+     * the canonical instance — callers MUST use the returned value, not the
+     * one passed in, so a second registration with the same id resolves to
+     * the original (deduplication by id).
+     */
+    acquire<T extends RefCountedResource>(resource: T): T;
+    /**
+     * Decrement refcount; release the resource when it hits zero. Throws
+     * on unknown id — silent no-ops would hide leaks.
+     */
+    release(id: string): Promise<void>;
+    /** Diagnostic: current refcount, or 0 when not present. */
+    refCount(id: string): number;
+    /** Diagnostic: snapshot of currently-tracked resource ids. */
+    ids(): ReadonlyArray<string>;
+    /** Total tracked resources. */
+    size(): number;
+}
+export {};
+//# sourceMappingURL=shared-resources.d.ts.map

package/services/local-inference/voice/shared-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-resources.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/shared-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2EAA2E;AAC3E,UAAU,MAAM;IACd,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,kBAAkB;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,oDAAoD;IACpD,QAAQ,IAAI,aAAa,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;CAC7C;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAOD;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAS;gBAElB,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAI1C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,kBAAkB,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAUrD;;;OAGG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAI5B,8DAA8D;IAC9D,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC;IAI5B,+BAA+B;IAC/B,IAAI,IAAI,MAAM;CAGf"}

package/services/local-inference/voice/shared-resources.js

@@ -0,0 +1,83 @@
+/**
+ * Cross-cut resource sharing between the text + voice surfaces of a
+ * single Eliza-1 bundle.
+ *
+ * Per `packages/inference/AGENTS.md` §4 ("shared KV cache scheduling,
+ * not shared KV memory" + "one process, one llama.cpp build, one GGML
+ * pin"), text and voice MUST share:
+ *   - the tokenizer (Eliza-1/OmniVoice share a vocabulary in this lineage),
+ *   - the mmap regions for weights (deduplicated by absolute path),
+ *   - the kernel set (same shipped llama.cpp library after fusion),
+ *   - the scheduler queue (one queue, prioritised),
+ *   - the DFlash drafter (always wired, see AGENTS.md §3 #4).
+ *
+ * What they do NOT share:
+ *   - KV cache memory (different layer counts, different head configs,
+ *     different quantizations — separate caches, shared scheduler).
+ *
+ * This module owns reference counts on each shared resource and is the
+ * single arbiter of when an mmap region can be released back to the OS
+ * via the `madvise` path documented in `lifecycle.ts`. It does NOT do
+ * any I/O itself — the actual mmap + page-eviction syscalls live behind
+ * the `MmapRegionHandle` interface so platform-specific bindings can
+ * implement them.
+ */
+/**
+ * Owns the shared resources for one engine. Voice + text both `acquire`
+ * and `release` against the same registry; the registry only releases
+ * the underlying resource when refcount hits zero.
+ *
+ * Thread-safety: all methods run on the single Node event loop; no
+ * locks needed. Promises returned from `release()` MUST be awaited so
+ * the lifecycle state machine can observe completion.
+ */
+export class SharedResourceRegistry {
+    entries = new Map();
+    log;
+    constructor(opts = {}) {
+        this.log = opts.logger;
+    }
+    /**
+     * Register a resource if absent, increment refcount otherwise. Returns
+     * the canonical instance — callers MUST use the returned value, not the
+     * one passed in, so a second registration with the same id resolves to
+     * the original (deduplication by id).
+     */
+    acquire(resource) {
+        const existing = this.entries.get(resource.id);
+        if (existing) {
+            existing.refCount++;
+            return existing.resource;
+        }
+        this.entries.set(resource.id, { resource, refCount: 1 });
+        return resource;
+    }
+    /**
+     * Decrement refcount; release the resource when it hits zero. Throws
+     * on unknown id — silent no-ops would hide leaks.
+     */
+    async release(id) {
+        const entry = this.entries.get(id);
+        if (!entry) {
+            throw new Error(`[shared-resources] release(${id}): unknown resource — possible double release or registry desync`);
+        }
+        entry.refCount--;
+        if (entry.refCount > 0)
+            return;
+        this.entries.delete(id);
+        await entry.resource.release();
+        this.log?.debug?.(`[SharedResourceRegistry] released ${id}`);
+    }
+    /** Diagnostic: current refcount, or 0 when not present. */
+    refCount(id) {
+        return this.entries.get(id)?.refCount ?? 0;
+    }
+    /** Diagnostic: snapshot of currently-tracked resource ids. */
+    ids() {
+        return Array.from(this.entries.keys());
+    }
+    /** Total tracked resources. */
+    size() {
+        return this.entries.size;
+    }
+}

package/services/local-inference/voice/speaker-preset-cache.d.ts

@@ -0,0 +1,28 @@
+import type { SpeakerPreset } from "./types";
+import { type VoicePresetSeedPhrase } from "./voice-preset-format";
+export interface PresetBundlePaths {
+    bundleRoot: string;
+    cacheRelPath?: string;
+}
+export interface LoadedPresetBundle {
+    preset: SpeakerPreset;
+    /** Phrase-cache seed entries parsed alongside the embedding. The engine
+     *  bridge feeds these into a `PhraseCache.seed(...)` call before the
+     *  scheduler is constructed. */
+    phrases: ReadonlyArray<VoicePresetSeedPhrase>;
+}
+export declare class SpeakerPresetCache {
+    private readonly cache;
+    private readonly seeds;
+    /**
+     * Load a voice-preset binary file and return both the speaker embedding
+     * and the phrase-cache seed entries. The embedding is also cached for
+     * subsequent `get()` lookups.
+     */
+    loadFromBundle(paths: PresetBundlePaths, voiceId?: string): LoadedPresetBundle;
+    put(preset: SpeakerPreset): void;
+    get(voiceId: string): SpeakerPreset | undefined;
+    /** Seed entries previously loaded for a voice, if any. */
+    getSeed(voiceId: string): ReadonlyArray<VoicePresetSeedPhrase>;
+}
+//# sourceMappingURL=speaker-preset-cache.d.ts.map

package/services/local-inference/voice/speaker-preset-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speaker-preset-cache.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/speaker-preset-cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB;;oCAEgC;IAChC,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CAC/C;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2D;IAEjF;;;;OAIG;IACH,cAAc,CACZ,KAAK,EAAE,iBAAiB,EACxB,OAAO,SAAY,GAClB,kBAAkB;IAuBrB,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIhC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI/C,0DAA0D;IAC1D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,qBAAqB,CAAC;CAG/D"}

package/services/local-inference/voice/speaker-preset-cache.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { readVoicePresetFile, } from "./voice-preset-format";
+const DEFAULT_REL_PATH = path.join("cache", "voice-preset-default.bin");
+export class SpeakerPresetCache {
+    cache = new Map();
+    seeds = new Map();
+    /**
+     * Load a voice-preset binary file and return both the speaker embedding
+     * and the phrase-cache seed entries. The embedding is also cached for
+     * subsequent `get()` lookups.
+     */
+    loadFromBundle(paths, voiceId = "default") {
+        const cached = this.cache.get(voiceId);
+        if (cached) {
+            return {
+                preset: cached,
+                phrases: this.seeds.get(voiceId) ?? [],
+            };
+        }
+        const rel = paths.cacheRelPath ?? DEFAULT_REL_PATH;
+        const fullPath = path.join(paths.bundleRoot, rel);
+        const bytes = readFileSync(fullPath);
+        const parsed = readVoicePresetFile(new Uint8Array(bytes));
+        const preset = {
+            voiceId,
+            embedding: parsed.embedding,
+            bytes: new Uint8Array(bytes),
+        };
+        this.cache.set(voiceId, preset);
+        this.seeds.set(voiceId, parsed.phrases);
+        return { preset, phrases: parsed.phrases };
+    }
+    put(preset) {
+        this.cache.set(preset.voiceId, preset);
+    }
+    get(voiceId) {
+        return this.cache.get(voiceId);
+    }
+    /** Seed entries previously loaded for a voice, if any. */
+    getSeed(voiceId) {
+        return this.seeds.get(voiceId) ?? [];
+    }
+}

package/services/local-inference/voice/types.d.ts

@@ -0,0 +1,80 @@
+export interface TextToken {
+    index: number;
+    text: string;
+}
+export interface AcceptedToken extends TextToken {
+    acceptedAt: number;
+}
+export interface RejectedTokenRange {
+    fromIndex: number;
+    toIndex: number;
+}
+export interface Phrase {
+    id: number;
+    text: string;
+    fromIndex: number;
+    toIndex: number;
+    terminator: "punctuation" | "max-cap" | "phoneme-stream";
+}
+export interface AudioChunk {
+    phraseId: number;
+    fromIndex: number;
+    toIndex: number;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+export interface SpeakerPreset {
+    voiceId: string;
+    embedding: Float32Array;
+    bytes: Uint8Array;
+}
+export interface AudioSink {
+    write(pcm: Float32Array, sampleRate: number): void;
+    drain(): void;
+    bufferedSamples(): number;
+}
+export interface OmniVoiceBackend {
+    synthesize(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onKernelTick?: () => void;
+    }): Promise<AudioChunk>;
+}
+export interface PhraseChunkerConfig {
+    maxTokensPerPhrase: number;
+    sentenceTerminators?: ReadonlySet<string>;
+    /**
+     * Where the chunker emits a phrase boundary.
+     *   'punctuation'    — default. Wait for sentence-final punctuation or
+     *                      the max-token cap.
+     *   'phoneme-stream' — additionally emit a sub-phrase chunk every
+     *                      `phonemesPerChunk` phonemes. Cuts first-audio
+     *                      latency by handing partial phrases to TTS at
+     *                      phoneme boundaries.
+     */
+    chunkOn?: "punctuation" | "phoneme-stream";
+    /** Phonemes per chunk in `phoneme-stream` mode. Default 8. */
+    phonemesPerChunk?: number;
+}
+export interface VerifierStreamEvent {
+    kind: "accept" | "reject";
+    tokens: TextToken[];
+}
+export interface SchedulerConfig {
+    chunkerConfig: PhraseChunkerConfig;
+    preset: SpeakerPreset;
+    ringBufferCapacity: number;
+    sampleRate: number;
+    /**
+     * Max concurrent TTS dispatches. When this many phrases are in flight,
+     * `accept()` awaits the oldest before dispatching the next, propagating
+     * backpressure upstream to the verifier loop. Default 4 — small enough
+     * to bound memory under runaway producers without serialising the
+     * common case (text gen leads TTS by a phrase or two).
+     */
+    maxInFlightPhrases?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/services/local-inference/voice/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,aAAa,GAAG,SAAS,GAAG,gBAAgB,CAAC;CAC1D;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,YAAY,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,YAAY,CAAC;IACxB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,KAAK,IAAI,IAAI,CAAC;IACd,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,aAAa,CAAC;QACtB,YAAY,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,CAAC;QACrC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;KAC3B,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,gBAAgB,CAAC;IAC3C,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,mBAAmB,CAAC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/services/local-inference/voice/voice-preset-format.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Binary format for `cache/voice-preset-default.bin`.
+ *
+ * Layout (little-endian throughout):
+ *
+ *   +0   4 bytes  magic 'ELZ1' (0x315A4C45)
+ *   +4   4 bytes  format version (uint32)               — v1
+ *   +8   4 bytes  speaker embedding offset (uint32)
+ *   +12  4 bytes  speaker embedding byte length (uint32)
+ *   +16  4 bytes  phrase cache seed offset (uint32)
+ *   +20  4 bytes  phrase cache seed byte length (uint32)
+ *   +24  ...      speaker embedding (Float32 LE vector)
+ *   +... ...      phrase cache seed:
+ *                   uint32 LE  N (phrase count)
+ *                   for each phrase:
+ *                     uint16 LE  text_byte_len
+ *                     uint8[]    canonicalized text (UTF-8)
+ *                     uint32 LE  sample_rate
+ *                     uint32 LE  pcm_byte_len
+ *                     uint8[]    PCM (Float32 LE samples)
+ *
+ * Both sections are mandatory in v1. An empty phrase cache seed is encoded
+ * as N=0 (4 bytes); zero-byte sections are not permitted (use N=0 instead).
+ */
+export declare const VOICE_PRESET_MAGIC = 828001349;
+export declare const VOICE_PRESET_VERSION = 1;
+export declare const VOICE_PRESET_HEADER_BYTES = 24;
+export interface VoicePresetSeedPhrase {
+    /** Canonicalized text (lowercase, single-spaced, trimmed). */
+    text: string;
+    sampleRate: number;
+    pcm: Float32Array;
+}
+export interface VoicePresetFile {
+    version: number;
+    embedding: Float32Array;
+    phrases: ReadonlyArray<VoicePresetSeedPhrase>;
+}
+export declare class VoicePresetFormatError extends Error {
+    readonly code: "bad-magic" | "bad-version" | "truncated-header" | "truncated-section" | "bad-section-bounds" | "bad-phrase-record" | "bad-embedding-length";
+    constructor(message: string, code: "bad-magic" | "bad-version" | "truncated-header" | "truncated-section" | "bad-section-bounds" | "bad-phrase-record" | "bad-embedding-length");
+}
+/**
+ * Parse a voice-preset binary blob. Throws `VoicePresetFormatError` on any
+ * malformed input — this is the single defensive boundary for the format.
+ */
+export declare function readVoicePresetFile(bytes: Uint8Array): VoicePresetFile;
+/**
+ * Serialize a voice preset to the v1 binary format. The output is a fresh
+ * `Uint8Array` ready to be written to disk.
+ */
+export declare function writeVoicePresetFile(file: {
+    embedding: Float32Array;
+    phrases: ReadonlyArray<VoicePresetSeedPhrase>;
+}): Uint8Array;
+//# sourceMappingURL=voice-preset-format.d.ts.map

package/services/local-inference/voice/voice-preset-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-preset-format.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/voice-preset-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,eAAO,MAAM,kBAAkB,YAAa,CAAC;AAC7C,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CAC/C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,IAAI,EACT,WAAW,GACX,aAAa,GACb,kBAAkB,GAClB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB;gBAR1B,OAAO,EAAE,MAAM,EACN,IAAI,EACT,WAAW,GACX,aAAa,GACb,kBAAkB,GAClB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB;CAK7B;AAoJD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,CAQtE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CAC/C,GAAG,UAAU,CA+Db"}