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

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

@@ -0,0 +1,189 @@
+/**
+ * Voice on/off state machine.
+ *
+ * Per `packages/inference/AGENTS.md` §4 + this scope's design goals,
+ * voice is OFF by default. Text + drafter are hot; TTS, ASR, the
+ * speaker preset cache and phrase cache, the chunker, the rollback
+ * queue, the barge-in controller, and the ring buffer are NOT in RAM.
+ *
+ * Transitions are explicit. Illegal transitions throw — no
+ * "log-and-continue" (AGENTS.md §9). The transition to `voice-off`
+ * MUST issue a real page-eviction call on the TTS/ASR mmap regions
+ * (see `MmapRegionHandle.evictPages()` in `shared-resources.ts`) so
+ * the OS can reclaim those pages.
+ *
+ *   ┌──────────┐ start()  ┌──────────────┐ armed   ┌──────────┐
+ *   │ voice-off│─────────▶│ voice-arming │────────▶│ voice-on │
+ *   └──────────┘          └──────────────┘         └──────────┘
+ *        ▲                       │ start fails           │ stop()
+ *        │ disarmed              ▼                       ▼
+ *  ┌──────────────────┐    ┌──────────────┐  ┌────────────────────┐
+ *  │ voice-disarming  │◀───│ voice-error  │  │  voice-disarming   │
+ *  └──────────────────┘    └──────────────┘  └────────────────────┘
+ *        │                                            │
+ *        └────────────────── disarmed ◀───────────────┘
+ *
+ * `voice-error` is terminal until `reset()` is called. There is no
+ * automatic retry: a missing kernel, mmap fail, or RAM-pressure
+ * refusal MUST surface to the caller.
+ */
+/**
+ * Structured failure surfaced to the caller. Never a generic `Error` —
+ * the caller (engine + UI) needs to distinguish RAM pressure from a
+ * missing kernel from a manifest mismatch (AGENTS.md §3).
+ */
+export class VoiceLifecycleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "VoiceLifecycleError";
+        this.code = code;
+    }
+}
+export class VoiceLifecycle {
+    state = { kind: "voice-off" };
+    registry;
+    loaders;
+    events;
+    constructor(args) {
+        this.registry = args.registry;
+        this.loaders = args.loaders;
+        this.events = args.events ?? {};
+    }
+    current() {
+        return this.state;
+    }
+    /**
+     * Transition `voice-off → voice-arming → voice-on`. Loads TTS + ASR
+     * mmap regions, voice caches, voice scheduler nodes. Each load throws
+     * on failure; a thrown loader transitions the state to `voice-error`
+     * and re-throws so the caller sees the structured cause. No partial
+     * arm: either all four resources are held or none are.
+     */
+    async arm() {
+        if (this.state.kind !== "voice-off") {
+            throw new VoiceLifecycleError("illegal-transition", `[voice-lifecycle] arm() called in state ${this.state.kind} — must be voice-off`);
+        }
+        this.transition({ kind: "voice-arming" });
+        let tts = null;
+        let asr = null;
+        let voiceCaches = null;
+        let voiceSchedulerNodes = null;
+        try {
+            tts = this.registry.acquire(await this.loaders.loadTtsRegion());
+            asr = this.registry.acquire(await this.loaders.loadAsrRegion());
+            voiceCaches = this.registry.acquire(await this.loaders.loadVoiceCaches());
+            voiceSchedulerNodes = this.registry.acquire(await this.loaders.loadVoiceSchedulerNodes());
+        }
+        catch (err) {
+            // Roll back partial acquisitions before surfacing the error so the
+            // registry doesn't leak refs on a failed arm.
+            const rollback = [
+                voiceSchedulerNodes,
+                voiceCaches,
+                asr,
+                tts,
+            ];
+            for (const res of rollback) {
+                if (res)
+                    await this.registry.release(res.id);
+            }
+            const lifecycleErr = toLifecycleError("arm-failed", err);
+            this.transition({ kind: "voice-error", error: lifecycleErr });
+            throw lifecycleErr;
+        }
+        const resources = {
+            tts,
+            asr,
+            voiceCaches,
+            voiceSchedulerNodes,
+        };
+        this.transition({ kind: "voice-on", resources });
+        return resources;
+    }
+    /**
+     * Transition `voice-on → voice-disarming → voice-off`. Calls
+     * `evictPages()` on the TTS + ASR mmap regions before releasing them
+     * so the OS reclaims the pages even if another consumer keeps the
+     * file descriptor open. The voice caches stay in the registry as
+     * tiny (KB-scale) entries — only the heavy mmap regions get evicted.
+     */
+    async disarm() {
+        if (this.state.kind !== "voice-on") {
+            throw new VoiceLifecycleError("illegal-transition", `[voice-lifecycle] disarm() called in state ${this.state.kind} — must be voice-on`);
+        }
+        const resources = this.state.resources;
+        this.transition({ kind: "voice-disarming", resources });
+        let evictionFailure = null;
+        // Eviction first — the mmap region is still mapped, the kernel can
+        // still drop the pages. If eviction fails we still proceed to
+        // release; the failure is captured and re-thrown after release so
+        // the registry stays consistent.
+        //
+        // `evictPages()` on production handles wires through to the
+        // `libelizainference` FFI (`ffi.mmapEvict(ctx, "tts" | "asr")`,
+        // declared in `scripts/omnivoice-fuse/ffi.h`). The fused build
+        // implements that as `madvise(MADV_DONTNEED)` on POSIX or
+        // `VirtualUnlock + OfferVirtualMemory` on Windows. The stub
+        // library returns ELIZA_ERR_NOT_IMPLEMENTED, which the binding
+        // raises as `VoiceLifecycleError({code:"kernel-missing"})` — this
+        // method captures it and re-classifies as `disarm-failed` after
+        // release runs (so registry refs don't leak on a bad eviction).
+        const evictResults = await Promise.allSettled([
+            resources.tts.evictPages(),
+            resources.asr.evictPages(),
+        ]);
+        for (const r of evictResults) {
+            if (r.status === "rejected" && evictionFailure === null) {
+                evictionFailure = r.reason;
+            }
+        }
+        // Release in reverse acquisition order.
+        await this.registry.release(resources.voiceSchedulerNodes.id);
+        await this.registry.release(resources.voiceCaches.id);
+        await this.registry.release(resources.asr.id);
+        await this.registry.release(resources.tts.id);
+        if (evictionFailure !== null) {
+            const err = toLifecycleError("disarm-failed", evictionFailure);
+            this.transition({ kind: "voice-error", error: err });
+            throw err;
+        }
+        this.transition({ kind: "voice-off" });
+    }
+    /**
+     * Reset from `voice-error` back to `voice-off`. Required because
+     * `voice-error` is terminal — the engine must explicitly acknowledge
+     * the failure before the user can re-attempt voice. There is no
+     * automatic retry path.
+     */
+    reset() {
+        if (this.state.kind !== "voice-error") {
+            throw new VoiceLifecycleError("illegal-transition", `[voice-lifecycle] reset() called in state ${this.state.kind} — must be voice-error`);
+        }
+        this.transition({ kind: "voice-off" });
+    }
+    transition(next) {
+        const prev = this.state;
+        this.state = next;
+        this.events.onTransition?.(prev, next);
+    }
+}
+function toLifecycleError(fallbackCode, err) {
+    if (err instanceof VoiceLifecycleError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    // Heuristic mapping of common platform-level signals into the
+    // structured codes documented above. The lifecycle never fabricates
+    // a code it didn't receive evidence for — anything that doesn't match
+    // one of these falls back to the caller-provided code.
+    if (/ENOMEM|out of memory|RAM/i.test(message)) {
+        return new VoiceLifecycleError("ram-pressure", message);
+    }
+    if (/mmap|MAP_FAILED/i.test(message)) {
+        return new VoiceLifecycleError("mmap-fail", message);
+    }
+    if (/kernel|missing kernel/i.test(message)) {
+        return new VoiceLifecycleError("kernel-missing", message);
+    }
+    return new VoiceLifecycleError(fallbackCode, message);
+}

package/services/local-inference/voice/phoneme-tokenizer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Phoneme tokenizer interface used by the IPA-mode phrase chunker.
+ *
+ * The chunker consumes a stream of accepted text tokens and re-emits them
+ * as sub-phrase chunks at phoneme boundaries. This lets TTS start
+ * synthesizing partial phrases ~250ms earlier than the punctuation-only
+ * mode, at the cost of slightly less prosody coherence per chunk.
+ *
+ * WAVE-7 DEPENDENCY:
+ *   The production tokenizer is an out-of-scope dependency. Candidates
+ *   evaluated in the architecture review:
+ *     - espeak-ng (C, FFI bridge, best coverage, GPL-3)
+ *     - phonemizer.js (pure JS port of espeak, MIT, slower)
+ *     - ipa-translate-rs (Rust, NAPI, fast, smaller language coverage)
+ *   The shipping decision lives in inference/AGENTS.md §6.4.
+ *
+ *   Until then, callers MUST pass `CharacterPhonemeStub` explicitly and
+ *   accept that the resulting chunk boundaries are character-aligned, not
+ *   phoneme-aligned. The stub logs a warning the first time it is used.
+ */
+export interface Phoneme {
+    /** IPA symbol(s) for this phoneme. With the stub, this is a single
+     *  source character — clearly NOT real IPA. */
+    ipa: string;
+    /** Index of the source `TextToken` this phoneme came from. Used by the
+     *  chunker to map sub-phrases back to token-index ranges so that the
+     *  rollback queue can still drop the right audio on a verifier reject. */
+    sourceTokenIndex: number;
+}
+export interface PhonemeTokenizer {
+    /** Stable tokenizer name, used for logging and cache keys. */
+    readonly name: string;
+    /** True if this is a placeholder. The IPA chunker logs prominently when
+     *  a stub is in use — production must replace it before launch. */
+    readonly isStub: boolean;
+    /**
+     * Tokenize a single text token's text into phonemes. The chunker calls
+     * this once per accepted token; the tokenizer returns the phonemes for
+     * that token only. Returning an empty array is legal (e.g. whitespace
+     * tokens) and is treated as "no phoneme boundary added by this token".
+     */
+    tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[];
+}
+/**
+ * Placeholder phoneme tokenizer that emits one phoneme per input character.
+ * Whitespace characters are skipped. This is NOT a real IPA tokenizer and
+ * the produced chunk boundaries are character boundaries, not phoneme
+ * boundaries. Suitable only for end-to-end wiring tests until a real
+ * tokenizer ships in Wave-7.
+ */
+export declare class CharacterPhonemeStub implements PhonemeTokenizer {
+    readonly name = "CharacterPhonemeStub";
+    readonly isStub = true;
+    tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[];
+}
+/** Reset the one-shot warn latch — test-only. */
+export declare function _resetStubWarnLatchForTests(): void;
+//# sourceMappingURL=phoneme-tokenizer.d.ts.map

package/services/local-inference/voice/phoneme-tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneme-tokenizer.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/phoneme-tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,OAAO;IACtB;mDAC+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ;;8EAE0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;uEACmE;IACnE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;CACtE;AAID;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,QAAQ,CAAC,IAAI,0BAA0B;IACvC,QAAQ,CAAC,MAAM,QAAQ;IAEvB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE;CAkBrE;AAED,iDAAiD;AACjD,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/services/local-inference/voice/phoneme-tokenizer.js

@@ -0,0 +1,53 @@
+/**
+ * Phoneme tokenizer interface used by the IPA-mode phrase chunker.
+ *
+ * The chunker consumes a stream of accepted text tokens and re-emits them
+ * as sub-phrase chunks at phoneme boundaries. This lets TTS start
+ * synthesizing partial phrases ~250ms earlier than the punctuation-only
+ * mode, at the cost of slightly less prosody coherence per chunk.
+ *
+ * WAVE-7 DEPENDENCY:
+ *   The production tokenizer is an out-of-scope dependency. Candidates
+ *   evaluated in the architecture review:
+ *     - espeak-ng (C, FFI bridge, best coverage, GPL-3)
+ *     - phonemizer.js (pure JS port of espeak, MIT, slower)
+ *     - ipa-translate-rs (Rust, NAPI, fast, smaller language coverage)
+ *   The shipping decision lives in inference/AGENTS.md §6.4.
+ *
+ *   Until then, callers MUST pass `CharacterPhonemeStub` explicitly and
+ *   accept that the resulting chunk boundaries are character-aligned, not
+ *   phoneme-aligned. The stub logs a warning the first time it is used.
+ */
+let stubWarned = false;
+/**
+ * Placeholder phoneme tokenizer that emits one phoneme per input character.
+ * Whitespace characters are skipped. This is NOT a real IPA tokenizer and
+ * the produced chunk boundaries are character boundaries, not phoneme
+ * boundaries. Suitable only for end-to-end wiring tests until a real
+ * tokenizer ships in Wave-7.
+ */
+export class CharacterPhonemeStub {
+    name = "CharacterPhonemeStub";
+    isStub = true;
+    tokenize(text, sourceTokenIndex) {
+        if (!stubWarned) {
+            stubWarned = true;
+            // Loud, one-shot. Production must NOT see this warning.
+            // Emitted via console.warn per the task contract.
+            // eslint-disable-next-line no-console
+            console.warn("[CharacterPhonemeStub] Using placeholder phoneme tokenizer — chunk boundaries are character boundaries, not IPA phonemes. Replace with a real tokenizer (espeak-ng / phonemizer.js / ipa-translate-rs) before production. See inference/AGENTS.md §6.4.");
+        }
+        const out = [];
+        for (let i = 0; i < text.length; i++) {
+            const ch = text[i];
+            if (/\s/.test(ch))
+                continue;
+            out.push({ ipa: ch, sourceTokenIndex });
+        }
+        return out;
+    }
+}
+/** Reset the one-shot warn latch — test-only. */
+export function _resetStubWarnLatchForTests() {
+    stubWarned = false;
+}

package/services/local-inference/voice/phrase-cache.d.ts

@@ -0,0 +1,24 @@
+export interface CachedPhraseAudio {
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+export declare function canonicalizePhraseText(text: string): string;
+export declare class PhraseCache {
+    private readonly entries;
+    put(entry: CachedPhraseAudio): void;
+    /**
+     * Pre-populate the cache from a voice-preset seed list. Texts are stored
+     * verbatim — callers (the format reader) are responsible for canonicalizing
+     * before serialization, but we re-canonicalize on insert to be safe.
+     */
+    seed(entries: ReadonlyArray<{
+        text: string;
+        pcm: Float32Array;
+        sampleRate: number;
+    }>): void;
+    get(text: string): CachedPhraseAudio | undefined;
+    has(text: string): boolean;
+    size(): number;
+}
+//# sourceMappingURL=phrase-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phrase-cache.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/phrase-cache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,YAAY,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,GAAG,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAInC;;;;OAIG;IACH,IAAI,CACF,OAAO,EAAE,aAAa,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,YAAY,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,GACD,IAAI;IAUP,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIhD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,MAAM;CAGf"}

package/services/local-inference/voice/phrase-cache.js

@@ -0,0 +1,32 @@
+export function canonicalizePhraseText(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+export class PhraseCache {
+    entries = new Map();
+    put(entry) {
+        this.entries.set(canonicalizePhraseText(entry.text), entry);
+    }
+    /**
+     * Pre-populate the cache from a voice-preset seed list. Texts are stored
+     * verbatim — callers (the format reader) are responsible for canonicalizing
+     * before serialization, but we re-canonicalize on insert to be safe.
+     */
+    seed(entries) {
+        for (const e of entries) {
+            this.entries.set(canonicalizePhraseText(e.text), {
+                text: e.text,
+                pcm: e.pcm,
+                sampleRate: e.sampleRate,
+            });
+        }
+    }
+    get(text) {
+        return this.entries.get(canonicalizePhraseText(text));
+    }
+    has(text) {
+        return this.entries.has(canonicalizePhraseText(text));
+    }
+    size() {
+        return this.entries.size;
+    }
+}

package/services/local-inference/voice/phrase-chunker.d.ts

@@ -0,0 +1,20 @@
+import type { PhonemeTokenizer } from "./phoneme-tokenizer";
+import type { AcceptedToken, Phrase, PhraseChunkerConfig, TextToken } from "./types";
+export declare class PhraseChunker {
+    private readonly config;
+    private buffer;
+    private nextPhraseId;
+    private readonly terminators;
+    private readonly chunkOn;
+    private readonly phonemesPerChunk;
+    private readonly tokenizer;
+    private phonemeCount;
+    constructor(config: PhraseChunkerConfig, tokenizer?: PhonemeTokenizer | null);
+    push(token: AcceptedToken): Phrase | null;
+    flushPending(): Phrase | null;
+    reset(): void;
+    private endsWithTerminator;
+    private flushAs;
+}
+export declare function chunkTokens(tokens: TextToken[], config: PhraseChunkerConfig, acceptedAt?: number, tokenizer?: PhonemeTokenizer | null): Phrase[];
+//# sourceMappingURL=phrase-chunker.d.ts.map

package/services/local-inference/voice/phrase-chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrase-chunker.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/phrase-chunker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,mBAAmB,EACnB,SAAS,EACV,MAAM,SAAS,CAAC;AAKjB,qBAAa,aAAa;IAUtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,YAAY,CAAK;gBAGN,MAAM,EAAE,mBAAmB,EAC5C,SAAS,GAAE,gBAAgB,GAAG,IAAW;IAgB3C,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;IAuBzC,YAAY,IAAI,MAAM,GAAG,IAAI;IAK7B,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,OAAO;CAgBhB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE,mBAAmB,EAC3B,UAAU,SAAI,EACd,SAAS,GAAE,gBAAgB,GAAG,IAAW,GACxC,MAAM,EAAE,CAUV"}

package/services/local-inference/voice/phrase-chunker.js

@@ -0,0 +1,85 @@
+const DEFAULT_TERMINATORS = new Set([".", "!", "?"]);
+const DEFAULT_PHONEMES_PER_CHUNK = 8;
+export class PhraseChunker {
+    config;
+    buffer = [];
+    nextPhraseId = 0;
+    terminators;
+    chunkOn;
+    phonemesPerChunk;
+    tokenizer;
+    phonemeCount = 0;
+    constructor(config, tokenizer = null) {
+        this.config = config;
+        this.terminators = config.sentenceTerminators ?? DEFAULT_TERMINATORS;
+        this.chunkOn = config.chunkOn ?? "punctuation";
+        this.phonemesPerChunk = Math.max(1, config.phonemesPerChunk ?? DEFAULT_PHONEMES_PER_CHUNK);
+        this.tokenizer = tokenizer;
+        if (this.chunkOn === "phoneme-stream" && this.tokenizer === null) {
+            throw new Error("PhraseChunker: chunkOn='phoneme-stream' requires a PhonemeTokenizer (pass CharacterPhonemeStub for testing or a real tokenizer for production)");
+        }
+    }
+    push(token) {
+        this.buffer.push(token);
+        // Punctuation always wins — a sentence-final marker forces a flush
+        // even in phoneme-stream mode.
+        if (this.endsWithTerminator(token.text)) {
+            return this.flushAs("punctuation");
+        }
+        if (this.chunkOn === "phoneme-stream" && this.tokenizer !== null) {
+            const phonemes = this.tokenizer.tokenize(token.text, token.index);
+            this.phonemeCount += phonemes.length;
+            if (this.phonemeCount >= this.phonemesPerChunk) {
+                return this.flushAs("phoneme-stream");
+            }
+        }
+        if (this.buffer.length >= this.config.maxTokensPerPhrase) {
+            return this.flushAs("max-cap");
+        }
+        return null;
+    }
+    flushPending() {
+        if (this.buffer.length === 0)
+            return null;
+        return this.flushAs("max-cap");
+    }
+    reset() {
+        this.buffer = [];
+        this.phonemeCount = 0;
+    }
+    endsWithTerminator(text) {
+        if (text.length === 0)
+            return false;
+        const last = text[text.length - 1];
+        return this.terminators.has(last);
+    }
+    flushAs(terminator) {
+        const tokens = this.buffer;
+        this.buffer = [];
+        this.phonemeCount = 0;
+        const fromIndex = tokens[0].index;
+        const toIndex = tokens[tokens.length - 1].index;
+        const text = tokens.map((t) => t.text).join("");
+        const phrase = {
+            id: this.nextPhraseId++,
+            text,
+            fromIndex,
+            toIndex,
+            terminator,
+        };
+        return phrase;
+    }
+}
+export function chunkTokens(tokens, config, acceptedAt = 0, tokenizer = null) {
+    const chunker = new PhraseChunker(config, tokenizer);
+    const phrases = [];
+    for (const t of tokens) {
+        const p = chunker.push({ ...t, acceptedAt });
+        if (p)
+            phrases.push(p);
+    }
+    const tail = chunker.flushPending();
+    if (tail)
+        phrases.push(tail);
+    return phrases;
+}

package/services/local-inference/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/services/local-inference/voice/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/ring-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAED,qBAAa,aAAa;IAQtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,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;gBAG5C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,EAChC,OAAO,GAAE,oBAAyB;IASpC,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;CAGvB;AAED,qBAAa,iBAAkB,YAAW,SAAS;IACjD,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;CAKvB"}

package/services/local-inference/voice/ring-buffer.js

@@ -0,0 +1,85 @@
+export class PcmRingBuffer {
+    capacity;
+    sampleRate;
+    sink;
+    buf;
+    readPos = 0;
+    writePos = 0;
+    filled = 0;
+    onOverflow;
+    constructor(capacity, sampleRate, sink, options = {}) {
+        this.capacity = capacity;
+        this.sampleRate = sampleRate;
+        this.sink = sink;
+        if (capacity <= 0) {
+            throw new Error("PcmRingBuffer: capacity must be positive");
+        }
+        this.buf = new Float32Array(capacity);
+        this.onOverflow = options.onOverflow;
+    }
+    write(pcm) {
+        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() {
+        return this.filled / this.capacity;
+    }
+    flushToSink() {
+        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() {
+        this.readPos = this.writePos;
+        this.filled = 0;
+        this.sink.drain();
+    }
+    size() {
+        return this.filled;
+    }
+    capacityHint() {
+        return this.capacity;
+    }
+}
+export class InMemoryAudioSink {
+    chunks = [];
+    buffered = 0;
+    write(pcm, sampleRate) {
+        this.chunks.push({ pcm, sampleRate });
+        this.buffered += pcm.length;
+    }
+    drain() {
+        this.buffered = 0;
+    }
+    bufferedSamples() {
+        return this.buffered;
+    }
+    totalWritten() {
+        let n = 0;
+        for (const c of this.chunks)
+            n += c.pcm.length;
+        return n;
+    }
+}

package/services/local-inference/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/services/local-inference/voice/rollback-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-queue.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/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;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,aAAa,EAAE,kBAAkB,CAAC;CACnC;AAED,qBAAa,aAAa;IACxB,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;CAGjB"}