@kuralle-syrinx/tts-core 4.4.0 → 4.5.0

package/dist/engine.d.ts

@@ -0,0 +1,30 @@
+import { type AudioFormat } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+import type { PacketSink, TimerPort, Transport, WireProtocol } from "./types.js";
+export interface TtsEngineDeps {
+    readonly protocol: WireProtocol;
+    readonly transport: Transport;
+    readonly sink: PacketSink;
+    readonly format: AudioFormat;
+    readonly sampleRateHz: number;
+    readonly provider: {
+        readonly name: string;
+        readonly model: string;
+        readonly region?: string;
+    };
+    /** 0 disables the finish-timeout fallback. */
+    readonly finishTimeoutMs: number;
+    /** Namespace for engine-emitted metrics, e.g. "tts.epsilon". */
+    readonly metricPrefix: string;
+    readonly timer?: TimerPort;
+    readonly now?: () => number;
+}
+export interface TtsEngine {
+    onText(text: string, contextId: string): Promise<void>;
+    onDone(contextId: string): Promise<void>;
+    onInterrupt(): Promise<void>;
+    onMessage(data: SocketData, isBinary: boolean): void;
+    onConnectionLost(error: Error): void;
+    close(): Promise<void>;
+}
+export declare function createTtsEngine(deps: TtsEngineDeps): TtsEngine;

package/dist/engine.js

@@ -0,0 +1,387 @@
+// SPDX-License-Identifier: MIT
+//
+// The streaming-TTS deep module. Owns the entire lifecycle that the cartesia/grok/epsilon
+// plugins each used to duplicate: per-key PCM16 carry, active/cancelled/pending-end
+// bookkeeping keyed on the provider's opaque attribution key, finish-timeout, error
+// categorization, packet emission, and connection-loss failure. Socket-free: depends only
+// on the injected ports (`WireProtocol`, `Transport`, `PacketSink`, `TimerPort`), so the
+// tricky behavior (odd-byte carry, multiplex refcount, cancel races, finish-timeout) is
+// unit-testable without a real WebSocket.
+import { Route, assertAudioPayload, categorizeTtsError, isRecoverable, } from "@kuralle-syrinx/core";
+const EMPTY = new Uint8Array(0);
+// Cancelled-context guard is per-turn (telephony rotates contextIds), so it must
+// stay bounded to a recent-turns window instead of growing for the whole call.
+const MAX_CANCELLED_CONTEXTS = 256;
+function boundedAdd(set, value, cap) {
+    set.add(value);
+    while (set.size > cap) {
+        const oldest = set.values().next().value;
+        if (oldest === undefined)
+            break;
+        set.delete(oldest);
+    }
+}
+const defaultTimer = {
+    set: (ms, fn) => setTimeout(fn, ms),
+    clear: (handle) => {
+        clearTimeout(handle);
+    },
+};
+export function createTtsEngine(deps) {
+    return new TtsEngineImpl(deps);
+}
+class TtsEngineImpl {
+    deps;
+    keyToContext = new Map();
+    contextKeys = new Map();
+    cancelledContexts = new Set();
+    carry = new Map();
+    pendingEnd = new Set();
+    finishTimers = new Map();
+    timer;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.timer = deps.timer ?? defaultTimer;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    async onText(text, contextId) {
+        if (!text.trim())
+            return;
+        if (this.cancelledContexts.has(contextId))
+            return;
+        const { key } = this.deps.protocol.attributionFor(contextId);
+        this.track(key, contextId);
+        const frames = this.deps.protocol.encodeText(key, text);
+        if (frames.length === 0) {
+            this.untrack(key);
+            return;
+        }
+        for (const frame of frames) {
+            if (!(await this.trySend(frame, contextId))) {
+                this.untrack(key);
+                return;
+            }
+        }
+    }
+    async onDone(contextId) {
+        if (this.cancelledContexts.has(contextId))
+            return;
+        const activeKeys = [...(this.contextKeys.get(contextId) ?? [])];
+        for (const frame of this.deps.protocol.encodeFinish(contextId, activeKeys)) {
+            await this.trySend(frame, contextId);
+        }
+        this.pendingEnd.add(contextId);
+        if (this.deps.finishTimeoutMs > 0 && this.hasActiveKeys(contextId)) {
+            this.scheduleFinishTimeout(contextId);
+        }
+        this.tryEmitEnd(contextId);
+    }
+    async onInterrupt() {
+        const contexts = new Set([...this.contextKeys.keys(), ...this.pendingEnd]);
+        for (const contextId of contexts)
+            await this.cancelContext(contextId);
+    }
+    onMessage(data, isBinary) {
+        let events;
+        try {
+            events = this.deps.protocol.decode(data, isBinary);
+        }
+        catch (err) {
+            this.failAll(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        for (const event of events)
+            this.dispatch(event);
+    }
+    dispatch(event) {
+        switch (event.type) {
+            case "audio":
+                this.handleAudio(event.key, event.pcm);
+                return;
+            case "utterance_end":
+                this.handleUtteranceEnd(event.key);
+                return;
+            case "context_end":
+                this.handleContextEnd(event.key);
+                return;
+            case "cancelled":
+                this.handleCancelled(event.key);
+                return;
+            case "error":
+                this.handleError(event.key, event.error, event.endsContext ?? false);
+                return;
+            case "sideband": {
+                const contextId = this.keyToContext.get(event.key);
+                if (contextId === undefined)
+                    return;
+                this.deps.sink.push(event.route, event.build(contextId, this.now()));
+                return;
+            }
+            case "ignore":
+                return;
+        }
+    }
+    onConnectionLost(error) {
+        this.failAll(error);
+    }
+    async close() {
+        this.pendingEnd.clear();
+        this.cancelledContexts.clear();
+        this.keyToContext.clear();
+        this.contextKeys.clear();
+        this.carry.clear();
+        for (const handle of this.finishTimers.values())
+            this.timer.clear(handle);
+        this.finishTimers.clear();
+        try {
+            for (const frame of this.deps.protocol.encodeClose()) {
+                await this.deps.transport.ensureReady();
+                this.deps.transport.send(frame);
+            }
+        }
+        catch {
+            // Best-effort session shutdown.
+        }
+        await this.deps.transport.close();
+    }
+    // ── inbound handling ──────────────────────────────────────────────────────
+    handleAudio(key, pcm) {
+        const contextId = this.keyToContext.get(key);
+        if (contextId === undefined || this.cancelledContexts.has(contextId))
+            return;
+        if (pcm.byteLength === 0)
+            return;
+        // After flush, finish-timeout is an inactivity watchdog: keep it armed only
+        // while the provider is silent. Active audio must reschedule so long turns
+        // (e.g. half-cascade dumping full text then tts.done early) are not cut mid-stream.
+        if (this.pendingEnd.has(contextId) && this.deps.finishTimeoutMs > 0) {
+            this.scheduleFinishTimeout(contextId);
+        }
+        const prev = this.carry.get(key) ?? EMPTY;
+        const buf = prev.byteLength === 0 ? pcm : concatBytes(prev, pcm);
+        const evenLen = buf.byteLength - (buf.byteLength % 2);
+        if (evenLen > 0) {
+            const audio = buf.subarray(0, evenLen);
+            try {
+                assertAudioPayload(this.deps.format, audio);
+            }
+            catch (err) {
+                this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            const packet = {
+                kind: "tts.audio",
+                contextId,
+                timestampMs: this.now(),
+                audio,
+                sampleRateHz: this.deps.sampleRateHz,
+                provider: {
+                    name: this.deps.provider.name,
+                    model: this.deps.provider.model,
+                    region: this.deps.provider.region ?? "global",
+                    cancelled: false,
+                },
+            };
+            this.deps.sink.push(Route.Main, packet);
+        }
+        this.carry.set(key, evenLen < buf.byteLength ? buf.subarray(evenLen) : EMPTY);
+    }
+    // One attribution unit finished. The context ends only when all its units are done AND
+    // `tts.done` has been seen (the refcount/multiplex model, e.g. epsilon).
+    handleUtteranceEnd(key) {
+        const contextId = this.keyToContext.get(key);
+        this.untrack(key);
+        if (contextId === undefined)
+            return;
+        if (this.cancelledContexts.has(contextId)) {
+            this.clearCancelledIfDrained(contextId);
+            return;
+        }
+        this.tryEmitEnd(contextId);
+    }
+    // The provider declared the whole context complete — end now, regardless of `tts.done`
+    // (the single-stream model: cartesia `done:true`, grok `audio.done`).
+    handleContextEnd(key) {
+        const contextId = this.keyToContext.get(key);
+        this.untrack(key);
+        if (contextId === undefined)
+            return;
+        if (this.cancelledContexts.has(contextId)) {
+            this.clearCancelledIfDrained(contextId);
+            return;
+        }
+        this.endContextNow(contextId);
+    }
+    handleCancelled(key) {
+        const contextId = this.keyToContext.get(key);
+        this.untrack(key);
+        if (contextId !== undefined && this.cancelledContexts.has(contextId))
+            this.clearCancelledIfDrained(contextId);
+    }
+    handleError(key, error, endsContext) {
+        const contextId = key !== null ? this.keyToContext.get(key) : undefined;
+        if (key !== null)
+            this.untrack(key);
+        if (contextId !== undefined && this.cancelledContexts.has(contextId)) {
+            this.clearCancelledIfDrained(contextId);
+            return;
+        }
+        this.emitError(contextId ?? "", error);
+        if (contextId === undefined)
+            return;
+        // A terminal error (provider coupled it with `done`) ends the context now, using the
+        // contextId captured above before untrack; otherwise end only if the refcount allows.
+        if (endsContext)
+            this.endContextNow(contextId);
+        else
+            this.tryEmitEnd(contextId);
+    }
+    /** Once a cancelled context fully drains, drop the cancelled flag so the id can be reused. */
+    clearCancelledIfDrained(contextId) {
+        if (!this.hasActiveKeys(contextId))
+            this.cancelledContexts.delete(contextId);
+    }
+    /** Emit `tts.end` for a context immediately and clear its pending/timeout state. */
+    endContextNow(contextId) {
+        this.pendingEnd.delete(contextId);
+        this.clearFinishTimeout(contextId);
+        this.emitEnd(contextId);
+    }
+    // ── bookkeeping ───────────────────────────────────────────────────────────
+    track(key, contextId) {
+        this.keyToContext.set(key, contextId);
+        let keys = this.contextKeys.get(contextId);
+        if (!keys) {
+            keys = new Set();
+            this.contextKeys.set(contextId, keys);
+        }
+        keys.add(key);
+    }
+    untrack(key) {
+        const contextId = this.keyToContext.get(key);
+        this.keyToContext.delete(key);
+        this.carry.delete(key);
+        if (contextId === undefined)
+            return;
+        const keys = this.contextKeys.get(contextId);
+        if (!keys)
+            return;
+        keys.delete(key);
+        if (keys.size === 0)
+            this.contextKeys.delete(contextId);
+    }
+    hasActiveKeys(contextId) {
+        return (this.contextKeys.get(contextId)?.size ?? 0) > 0;
+    }
+    async cancelContext(contextId) {
+        boundedAdd(this.cancelledContexts, contextId, MAX_CANCELLED_CONTEXTS);
+        this.pendingEnd.delete(contextId);
+        this.clearFinishTimeout(contextId);
+        for (const key of [...(this.contextKeys.get(contextId) ?? [])]) {
+            for (const frame of this.deps.protocol.encodeCancel(key, contextId)) {
+                await this.trySend(frame, contextId);
+            }
+        }
+    }
+    tryEmitEnd(contextId) {
+        if (!this.pendingEnd.has(contextId))
+            return;
+        if (this.hasActiveKeys(contextId))
+            return;
+        this.pendingEnd.delete(contextId);
+        this.clearFinishTimeout(contextId);
+        this.cancelledContexts.delete(contextId);
+        this.emitEnd(contextId);
+    }
+    failAll(error) {
+        const contexts = new Set([...this.contextKeys.keys(), ...this.pendingEnd]);
+        this.pendingEnd.clear();
+        this.contextKeys.clear();
+        this.keyToContext.clear();
+        this.carry.clear();
+        let emitted = 0;
+        for (const contextId of contexts) {
+            this.clearFinishTimeout(contextId);
+            // Don't surface an error for a context the caller deliberately cancelled (e.g. a
+            // barge-in) when the socket drops before the provider acks the cancel.
+            if (this.cancelledContexts.has(contextId))
+                continue;
+            this.emitError(contextId, error);
+            emitted += 1;
+        }
+        this.cancelledContexts.clear();
+        if (emitted === 0 && contexts.size === 0)
+            this.emitError("", error);
+    }
+    // ── timers ────────────────────────────────────────────────────────────────
+    scheduleFinishTimeout(contextId) {
+        this.clearFinishTimeout(contextId);
+        const handle = this.timer.set(this.deps.finishTimeoutMs, () => {
+            this.finishTimers.delete(contextId);
+            if (!this.pendingEnd.has(contextId) && !this.hasActiveKeys(contextId))
+                return;
+            this.emitMetric(contextId, `${this.deps.metricPrefix}.finish_timeout`, String(this.deps.finishTimeoutMs));
+            this.pendingEnd.delete(contextId);
+            for (const key of [...(this.contextKeys.get(contextId) ?? [])])
+                this.untrack(key);
+            this.cancelledContexts.delete(contextId);
+            this.emitEnd(contextId);
+        });
+        this.finishTimers.set(contextId, handle);
+    }
+    clearFinishTimeout(contextId) {
+        const handle = this.finishTimers.get(contextId);
+        if (handle === undefined)
+            return;
+        this.timer.clear(handle);
+        this.finishTimers.delete(contextId);
+    }
+    // ── emission ──────────────────────────────────────────────────────────────
+    async trySend(frame, contextId) {
+        try {
+            await this.deps.transport.ensureReady();
+            this.deps.transport.send(frame);
+            return true;
+        }
+        catch (err) {
+            this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+            return false;
+        }
+    }
+    emitEnd(contextId) {
+        this.deps.sink.push(Route.Main, {
+            kind: "tts.end",
+            contextId,
+            timestampMs: this.now(),
+        });
+    }
+    emitError(contextId, err) {
+        const category = categorizeTtsError(err);
+        const packet = {
+            kind: "tts.error",
+            contextId,
+            timestampMs: this.now(),
+            component: "tts",
+            category,
+            cause: err,
+            isRecoverable: isRecoverable(category),
+        };
+        this.deps.sink.push(Route.Critical, packet);
+    }
+    emitMetric(contextId, name, value) {
+        this.deps.sink.push(Route.Background, {
+            kind: "metric.conversation",
+            contextId,
+            timestampMs: this.now(),
+            name,
+            value,
+        });
+    }
+}
+function concatBytes(a, b) {
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a, 0);
+    out.set(b, a.byteLength);
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createTtsEngine, type TtsEngine, type TtsEngineDeps } from "./engine.js";
+export { startStreamingTtsSession, defaultNodeSocketFactory, type StreamingTtsSpec, type StreamingTtsSession, } from "./plugin.js";
+export { attributionKey, type AttributionKey, type WireEvent, type WireProtocol, type Transport, type TimerPort, type TimerHandle, type PacketSink, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+export { createTtsEngine } from "./engine.js";
+export { startStreamingTtsSession, defaultNodeSocketFactory, } from "./plugin.js";
+export { attributionKey, } from "./types.js";

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+import { type AudioFormat, type PipelineBus, type RetryConfig } from "@kuralle-syrinx/core";
+import { type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+import type { WireProtocol } from "./types.js";
+export interface StreamingTtsSpec {
+    readonly protocol: WireProtocol;
+    readonly provider: {
+        readonly name: string;
+        readonly model: string;
+        readonly region?: string;
+    };
+    readonly format: AudioFormat;
+    readonly sampleRateHz: number;
+    readonly url: () => string;
+    readonly headers?: Record<string, string>;
+    readonly retry: RetryConfig;
+    readonly finishTimeoutMs: number;
+    readonly metricPrefix: string;
+    readonly socketFactory: SocketFactory;
+    readonly maxReconnectAttempts?: number;
+    readonly connectTimeoutMs?: number;
+    readonly replayBufferSize?: number;
+    readonly keepAliveIntervalMs?: number;
+    readonly keepAliveMessage?: () => SocketData;
+}
+export interface StreamingTtsSession {
+    dispose(): Promise<void>;
+}
+/** Open the provider socket, wire the bus, and return a handle whose `dispose()` tears it all down. */
+export declare function startStreamingTtsSession(bus: PipelineBus, spec: StreamingTtsSpec): Promise<StreamingTtsSession>;
+/** Default Node socket factory — lazily imported so the heavy `ws` dep only loads when used. */
+export declare function defaultNodeSocketFactory(): Promise<SocketFactory>;

package/dist/plugin.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+//
+// Ergonomic factory: wires a provider `WireProtocol` into a running streaming-TTS session
+// over a `WebSocketConnection`-backed transport, with the standard PipelineBus wiring
+// (tts.text→onText / tts.done→onDone / interrupt.tts→onInterrupt). A provider's published
+// `*TTSPlugin` class delegates `initialize`/`close` to this — its public surface is unchanged.
+import { Route } from "@kuralle-syrinx/core";
+import { WebSocketConnection } from "@kuralle-syrinx/ws";
+import { createTtsEngine } from "./engine.js";
+/** Open the provider socket, wire the bus, and return a handle whose `dispose()` tears it all down. */
+export async function startStreamingTtsSession(bus, spec) {
+    let conn;
+    const engine = createTtsEngine({
+        protocol: spec.protocol,
+        transport: {
+            ensureReady: () => conn.ensureReady(),
+            send: (frame) => conn.send(frame),
+            close: () => conn.close(),
+        },
+        sink: { push: (route, packet) => bus.push(route, packet) },
+        format: spec.format,
+        sampleRateHz: spec.sampleRateHz,
+        provider: spec.provider,
+        finishTimeoutMs: spec.finishTimeoutMs,
+        metricPrefix: spec.metricPrefix,
+    });
+    conn = new WebSocketConnection({
+        url: spec.url,
+        headers: spec.headers,
+        socketFactory: spec.socketFactory,
+        retry: spec.retry,
+        maxReconnectAttempts: spec.maxReconnectAttempts,
+        connectTimeoutMs: spec.connectTimeoutMs,
+        replayBufferSize: spec.replayBufferSize,
+        keepAliveIntervalMs: spec.keepAliveIntervalMs,
+        keepAliveMessage: spec.keepAliveMessage,
+        onMessage: (data, isBinary) => engine.onMessage(data, isBinary),
+        onConnectionLost: (err) => engine.onConnectionLost(err),
+        onUnrecoverable: (err) => engine.onConnectionLost(err),
+        onReplay: (event, count) => bus.push(Route.Background, {
+            kind: "metric.conversation",
+            contextId: "",
+            timestampMs: Date.now(),
+            name: `${spec.metricPrefix}.reconnect_replay_${event}`,
+            value: String(count),
+        }),
+    });
+    await conn.connect();
+    const disposers = [
+        bus.on("tts.text", async (pkt) => {
+            const textPkt = pkt;
+            await engine.onText(textPkt.text, textPkt.contextId);
+        }),
+        bus.on("tts.done", async (pkt) => {
+            const donePkt = pkt;
+            await engine.onDone(donePkt.contextId);
+        }),
+        bus.on("interrupt.tts", () => {
+            engine.onInterrupt().catch(() => {
+                // Best-effort interruption.
+            });
+        }),
+    ];
+    return {
+        dispose: async () => {
+            for (const dispose of disposers.splice(0))
+                dispose();
+            await engine.close();
+        },
+    };
+}
+/** Default Node socket factory — lazily imported so the heavy `ws` dep only loads when used. */
+export async function defaultNodeSocketFactory() {
+    const mod = await import("@kuralle-syrinx/ws/node");
+    return mod.createNodeWsSocket;
+}

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+import type { Route } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+/**
+ * Opaque attribution key. The engine NEVER parses it — it only uses it as a map key for
+ * carry/active/cancel bookkeeping. Providers mint it: a per-context provider returns the
+ * contextId; a single-stream provider returns a constant; a multiplexed provider returns
+ * `${contextId}:${seq}`. The single/per-context/per-request distinction is entirely a
+ * function of what key `WireProtocol.attributionFor` returns — there is no mode flag.
+ */
+export type AttributionKey = string & {
+    readonly __brand: "TtsAttributionKey";
+};
+export declare function attributionKey(value: string): AttributionKey;
+/**
+ * Decoded result of one inbound provider frame — a list, because a single frame can carry
+ * several aspects (e.g. cartesia ships audio + word-timestamps + a done flag together).
+ *
+ * `utterance_end` vs `context_end` is the one real semantic split between providers:
+ * - `utterance_end` — one attribution unit finished; the context ends only once every unit
+ *   is done AND the engine has seen `tts.done` (the multiplexed/refcount model, e.g. epsilon).
+ * - `context_end` — the provider declares the whole context complete; emit `tts.end` now,
+ *   regardless of `tts.done` (the single-stream model, e.g. cartesia `done:true`, grok `audio.done`).
+ */
+export type WireEvent = {
+    readonly type: "audio";
+    readonly key: AttributionKey;
+    readonly pcm: Uint8Array;
+} | {
+    readonly type: "utterance_end";
+    readonly key: AttributionKey;
+} | {
+    readonly type: "context_end";
+    readonly key: AttributionKey;
+} | {
+    readonly type: "cancelled";
+    readonly key: AttributionKey;
+} | {
+    readonly type: "error";
+    readonly key: AttributionKey | null;
+    readonly error: Error;
+    /** When true, this error is also the context's terminal signal → emit `tts.end` too
+     *  (e.g. cartesia's `{type:"error", done:true}`). Default false: report the error only. */
+    readonly endsContext?: boolean;
+} | {
+    readonly type: "sideband";
+    readonly key: AttributionKey;
+    readonly route: Route;
+    readonly build: (contextId: string, timestampMs: number) => unknown;
+} | {
+    readonly type: "ignore";
+};
+/**
+ * DRIVEN PORT — the provider wire protocol. Pure of sockets, timers, and the bus. This is the
+ * only surface a provider implements; everything else lives in the engine.
+ */
+export interface WireProtocol {
+    /** Mint the attribution key (and echo the contextId) for a new utterance request. */
+    attributionFor(contextId: string): {
+        readonly key: AttributionKey;
+        readonly contextId: string;
+    };
+    /** Encode a text chunk into the exact wire frame(s) to send. Return `[]` to send nothing. */
+    encodeText(key: AttributionKey, text: string): readonly SocketData[];
+    /** Encode the "no more text for this context" frame(s). `[]` if the provider has none. */
+    encodeFinish(contextId: string, activeKeys: readonly AttributionKey[]): readonly SocketData[];
+    /** Encode the cancel frame(s) for one attribution key. `[]` if the provider has no cancel. */
+    encodeCancel(key: AttributionKey, contextId: string): readonly SocketData[];
+    /** Optional session-teardown frame(s) sent best-effort on close (e.g. `{type:"eos"}`). */
+    encodeClose(): readonly SocketData[];
+    /** Decode one inbound socket frame into domain events (0+). Throwing is treated as fatal. */
+    decode(data: SocketData, isBinary: boolean): readonly WireEvent[];
+}
+/** DRIVEN PORT — transport. Production wraps a `WebSocketConnection`; tests pass a fake. */
+export interface Transport {
+    ensureReady(): Promise<void>;
+    send(frame: SocketData): void;
+    close(): Promise<void>;
+}
+export type TimerHandle = unknown;
+/** Injectable timers so finish-timeout behavior is deterministic in tests. */
+export interface TimerPort {
+    set(ms: number, fn: () => void): TimerHandle;
+    clear(handle: TimerHandle): void;
+}
+/** The bus, narrowed to the one method the engine needs. Injectable for socket-free tests. */
+export interface PacketSink {
+    push(route: Route, packet: unknown): void;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+//
+// Ports for the shared streaming-TTS deep module. The domain core (`engine.ts`) depends
+// only on these interfaces — never on a concrete socket or a specific provider. Each
+// provider supplies a `WireProtocol`; the runtime supplies a `Transport`.
+export function attributionKey(value) {
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/tts-core",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "private": false,
   "description": "Shared streaming-TTS lifecycle engine for Syrinx TTS adapters — carry, refcount, finish-timeout, cancel",
   "keywords": [
@@ -22,18 +22,25 @@
     "url": "https://github.com/kuralle/syrinx/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.4.0",
-    "@kuralle-syrinx/ws": "4.4.0"
+    "@kuralle-syrinx/core": "4.5.0",
+    "@kuralle-syrinx/ws": "4.5.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/engine.test.ts

@@ -0,0 +1,330 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { Route, type AudioFormat } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+import { createTtsEngine } from "./engine.js";
+import { attributionKey, type AttributionKey, type TimerHandle, type TimerPort, type Transport, type WireEvent, type WireProtocol } from "./types.js";
+
+const FORMAT: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 24000, channels: 1 };
+const SESSION = attributionKey("session");
+
+class FakeTimer implements TimerPort {
+  private readonly timers = new Map<number, { due: number; fn: () => void }>();
+  private next = 0;
+  private time = 0;
+  set(ms: number, fn: () => void): TimerHandle {
+    const handle = this.next++;
+    this.timers.set(handle, { due: this.time + ms, fn });
+    return handle;
+  }
+  clear(handle: TimerHandle): void {
+    this.timers.delete(handle as number);
+  }
+  /** Advance the fake clock; fire any timers whose due time is now reached. */
+  advance(ms: number): void {
+    this.time += ms;
+    this.fireDue();
+  }
+  /** Fire every pending timer immediately (legacy tests). */
+  fire(): void {
+    for (const [handle, entry] of [...this.timers]) {
+      this.timers.delete(handle);
+      entry.fn();
+    }
+  }
+  private fireDue(): void {
+    let progressed = true;
+    while (progressed) {
+      progressed = false;
+      const due = [...this.timers.entries()]
+        .filter(([, e]) => e.due <= this.time)
+        .sort((a, b) => a[1].due - b[1].due);
+      for (const [handle, entry] of due) {
+        if (!this.timers.has(handle)) continue;
+        this.timers.delete(handle);
+        entry.fn();
+        progressed = true;
+      }
+    }
+  }
+}
+
+/** grok-shape: one constant key per session. */
+class SingleProtocol implements WireProtocol {
+  attributionFor(contextId: string) {
+    return { key: SESSION, contextId };
+  }
+  encodeText(_key: AttributionKey, text: string): SocketData[] {
+    return [JSON.stringify({ op: "text", text })];
+  }
+  encodeFinish(): SocketData[] {
+    return [JSON.stringify({ op: "finish" })];
+  }
+  encodeCancel(): SocketData[] {
+    return [JSON.stringify({ op: "clear" })];
+  }
+  encodeClose(): SocketData[] {
+    return [];
+  }
+  decode(data: SocketData): WireEvent[] {
+    return decodeTestFrame(data, SESSION);
+  }
+}
+
+/** epsilon-shape: per-request key `${ctx}:${seq}`, refcount-driven end (no finish frame). */
+class MultiplexProtocol implements WireProtocol {
+  private readonly seq = new Map<string, number>();
+  attributionFor(contextId: string) {
+    const n = this.seq.get(contextId) ?? 0;
+    this.seq.set(contextId, n + 1);
+    return { key: attributionKey(`${contextId}:${n}`), contextId };
+  }
+  encodeText(key: AttributionKey, text: string): SocketData[] {
+    return [JSON.stringify({ op: "speak", key, text })];
+  }
+  encodeFinish(): SocketData[] {
+    return [];
+  }
+  encodeCancel(key: AttributionKey): SocketData[] {
+    return [JSON.stringify({ op: "cancel", key })];
+  }
+  encodeClose(): SocketData[] {
+    return [JSON.stringify({ op: "eos" })];
+  }
+  decode(data: SocketData): WireEvent[] {
+    return decodeTestFrame(data, null);
+  }
+}
+
+function decodeTestFrame(data: SocketData, fixedKey: AttributionKey | null): WireEvent[] {
+  const m = JSON.parse(data as string) as { t?: string; key?: string; pcm?: number[]; msg?: string };
+  const key = (m.key !== undefined ? attributionKey(m.key) : fixedKey) ?? SESSION;
+  switch (m.t) {
+    case "audio":
+      return [{ type: "audio", key, pcm: Uint8Array.from(m.pcm ?? []) }];
+    case "done":
+      return [{ type: "utterance_end", key }];
+    case "end":
+      return [{ type: "context_end", key }];
+    case "err":
+      return [{ type: "error", key: m.key !== undefined ? key : null, error: new Error(m.msg ?? "err") }];
+    case "boom":
+      throw new Error("decode failure");
+    default:
+      return [];
+  }
+}
+
+function harness(protocol: WireProtocol, finishTimeoutMs = 2000, opts: { sendThrows?: boolean } = {}) {
+  const sent: SocketData[] = [];
+  const pushed: Array<{ route: Route; packet: Record<string, unknown> }> = [];
+  const timer = new FakeTimer();
+  const transport: Transport = {
+    ensureReady: async () => {},
+    send: (frame) => {
+      if (opts.sendThrows) throw new Error("WebSocket is not open");
+      sent.push(frame);
+    },
+    close: async () => {},
+  };
+  const engine = createTtsEngine({
+    protocol,
+    transport,
+    sink: { push: (route, packet) => pushed.push({ route, packet: packet as Record<string, unknown> }) },
+    format: FORMAT,
+    sampleRateHz: 24000,
+    provider: { name: "fake", model: "m" },
+    finishTimeoutMs,
+    metricPrefix: "tts.fake",
+    timer,
+    now: () => 1000,
+  });
+  const byKind = (kind: string) => pushed.filter((p) => p.packet["kind"] === kind).map((p) => p.packet);
+  return { engine, sent, pushed, timer, audio: () => byKind("tts.audio"), ends: () => byKind("tts.end"), errors: () => byKind("tts.error"), metrics: () => byKind("metric.conversation") };
+}
+
+describe("TtsEngine — single-context (grok-shape)", () => {
+  it("carries an odd trailing byte across frames, then emits aligned PCM and ends on utterance_end", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("hello", "ctx1");
+    expect(h.sent).toEqual([JSON.stringify({ op: "text", text: "hello" })]);
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [1] }), false);
+    expect(h.audio()).toHaveLength(0); // 1 byte → odd, fully carried, nothing aligned yet
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [2, 3] }), false);
+    expect(h.audio()).toHaveLength(1); // [1] + [2,3] = [1,2,3] → emit [1,2], carry [3]
+    expect([...(h.audio()[0]!["audio"] as Uint8Array)]).toEqual([1, 2]);
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [4] }), false);
+    expect(h.audio()).toHaveLength(2); // [3] + [4] = [3,4] → emit [3,4]
+    expect([...(h.audio()[1]!["audio"] as Uint8Array)]).toEqual([3, 4]);
+
+    await h.engine.onDone("ctx1");
+    expect(h.sent).toContainEqual(JSON.stringify({ op: "finish" }));
+    expect(h.ends()).toHaveLength(0); // still streaming
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+  });
+
+  it("emits tts.end immediately on a provider context_end, with no prior tts.done", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxCE");
+    h.engine.onMessage(JSON.stringify({ t: "end", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1); // single-stream providers end on the provider's own done signal
+  });
+
+  it("drops audio after interrupt and sends the cancel frame", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxC");
+    await h.engine.onInterrupt();
+    expect(h.sent).toContainEqual(JSON.stringify({ op: "clear" }));
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [1, 2] }), false);
+    expect(h.audio()).toHaveLength(0);
+  });
+});
+
+describe("TtsEngine — multiplex (epsilon-shape)", () => {
+  it("emits tts.end only after every per-request key for a context completes", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxM"); // ctxM:0
+    await h.engine.onText("b", "ctxM"); // ctxM:1
+    expect(h.sent).toHaveLength(2);
+
+    await h.engine.onDone("ctxM"); // no finish frame; both requests still active
+    expect(h.ends()).toHaveLength(0);
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "ctxM:0" }), false);
+    expect(h.ends()).toHaveLength(0); // one still streaming
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "ctxM:1" }), false);
+    expect(h.ends()).toHaveLength(1); // refcount hit zero
+  });
+
+  it("attributes audio per request key independently", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxM"); // ctxM:0
+    await h.engine.onText("b", "ctxM"); // ctxM:1
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "ctxM:0", pcm: [1, 2] }), false);
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "ctxM:1", pcm: [3, 4] }), false);
+    const audio = h.audio();
+    expect(audio).toHaveLength(2);
+    expect(audio.every((p) => p["contextId"] === "ctxM")).toBe(true);
+  });
+});
+
+describe("TtsEngine — finish-timeout inactivity watchdog", () => {
+  const FINISH_MS = 2000;
+  const EPS = 500; // advance finishTimeoutMs - ε between audio frames
+
+  it("does not end while audio keeps arriving after flush (even past finishTimeoutMs total)", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("long turn", "ctxStream");
+    await h.engine.onDone("ctxStream");
+    expect(h.ends()).toHaveLength(0);
+
+    // Three chunks spaced (FINISH_MS - ε) apart → wall time > FINISH_MS, but never silent that long.
+    const chunks = [
+      [1, 2],
+      [3, 4],
+      [5, 6],
+    ] as const;
+    for (let i = 0; i < chunks.length; i++) {
+      if (i > 0) h.timer.advance(FINISH_MS - EPS);
+      h.engine.onMessage(
+        JSON.stringify({ t: "audio", key: "session", pcm: [...chunks[i]!] }),
+        false,
+      );
+      expect(h.ends()).toHaveLength(0);
+    }
+
+    expect(h.audio()).toHaveLength(3);
+    expect([...(h.audio()[0]!["audio"] as Uint8Array)]).toEqual([1, 2]);
+    expect([...(h.audio()[1]!["audio"] as Uint8Array)]).toEqual([3, 4]);
+    expect([...(h.audio()[2]!["audio"] as Uint8Array)]).toEqual([5, 6]);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(false);
+
+    // Natural provider end still closes the turn.
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+  });
+
+  it("still fires finish-timeout after finishTimeoutMs of silence post-flush (wedged provider)", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("a", "ctxWedge");
+    await h.engine.onDone("ctxWedge");
+    expect(h.ends()).toHaveLength(0);
+
+    h.timer.advance(FINISH_MS - 1);
+    expect(h.ends()).toHaveLength(0);
+
+    h.timer.advance(1);
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(true);
+  });
+
+  it("ends immediately on natural context_end even if finish-timeout is armed", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("a", "ctxNatural");
+    await h.engine.onDone("ctxNatural");
+    expect(h.ends()).toHaveLength(0);
+
+    h.engine.onMessage(JSON.stringify({ t: "end", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+    // Armed timer must not emit a second end or a finish_timeout metric.
+    h.timer.advance(FINISH_MS * 2);
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(false);
+  });
+});
+
+describe("TtsEngine — fallbacks and failures", () => {
+  it("fires the finish-timeout: emits a metric and tts.end when the provider never reports done", async () => {
+    const h = harness(new SingleProtocol(), 2000);
+    await h.engine.onText("a", "ctxD");
+    await h.engine.onDone("ctxD");
+    expect(h.ends()).toHaveLength(0);
+    h.timer.fire();
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(true);
+  });
+
+  it("maps a provider error frame to a categorized tts.error", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxE");
+    h.engine.onMessage(JSON.stringify({ t: "err", key: "session", msg: "provider boom" }), false);
+    const errors = h.errors();
+    expect(errors).toHaveLength(1);
+    expect((errors[0]!["cause"] as Error).message).toBe("provider boom");
+    expect(typeof errors[0]!["isRecoverable"]).toBe("boolean");
+  });
+
+  it("treats a decode throw as fatal and fails all active contexts", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxF");
+    h.engine.onMessage(JSON.stringify({ t: "boom" }), false);
+    expect(h.errors().some((e) => e["contextId"] === "ctxF")).toBe(true);
+  });
+
+  it("emits tts.error and does not leave the context active when a send fails", async () => {
+    const h = harness(new SingleProtocol(), 2000, { sendThrows: true });
+    await h.engine.onText("a", "ctxSend");
+    expect(h.errors().some((e) => e["contextId"] === "ctxSend")).toBe(true); // send failure → typed error
+    await h.engine.onDone("ctxSend");
+    expect(h.ends().some((e) => e["contextId"] === "ctxSend")).toBe(true); // context drained, turn ends (no hang)
+  });
+
+  it("fails active contexts on connection loss", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxG");
+    h.engine.onConnectionLost(new Error("dropped"));
+    expect(h.errors().some((e) => e["contextId"] === "ctxG")).toBe(true);
+  });
+
+  it("does not error a cancelled context when the connection then drops (barge-in race)", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxCancelled");
+    await h.engine.onInterrupt(); // cancel sent; key still tracked pending the provider ack
+    h.engine.onConnectionLost(new Error("dropped"));
+    expect(h.errors().some((e) => e["contextId"] === "ctxCancelled")).toBe(false);
+  });
+});