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

package/src/services/voice/kokoro/voices.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Kokoro-82M voice catalog.
+ *
+ * Re-exports the bundled `KOKORO_VOICE_PACKS` table from `voice-presets.ts`
+ * under the canonical filename the integration spec calls out, and adds a few
+ * search helpers used by the runtime-selection layer and the picker UI.
+ *
+ * Each voice pack ships as a small (~256 fp32 values × 4 bytes ≈ 1 KB) style
+ * tensor under `<modelRoot>/voices/<file>`. Adding voices is cheap (download
+ * a single .bin), and a hot ONNX session can swap voices per-utterance with
+ * no re-init cost — the model is the same.
+ *
+ * Upstream registry: https://huggingface.co/hexgrad/Kokoro-82M/tree/main/voices
+ */
+import type { KokoroVoiceId, KokoroVoicePack } from "./types";
+export { findKokoroVoice, KOKORO_DEFAULT_VOICE_ID, KOKORO_VOICE_PACKS, } from "./voice-presets";
+/** All voice ids that ship with the upstream Kokoro v1.0 release. */
+export declare function listKokoroVoiceIds(): ReadonlyArray<KokoroVoiceId>;
+/** Filter voice packs by language tag (`a` US, `b` UK, etc.). */
+export declare function listKokoroVoicesByLang(lang: string): ReadonlyArray<KokoroVoicePack>;
+/** Filter by an exact tag (`female`, `male`, `british`, `breathy`, ...). */
+export declare function listKokoroVoicesByTag(tag: string): ReadonlyArray<KokoroVoicePack>;
+/**
+ * Resolve a caller-supplied voice id against the registry. Returns the
+ * matching pack, or the default pack when the id is not bundled. Never
+ * throws — runtime selection treats this as a graceful fallback because the
+ * caller's `SpeakerPreset.voiceId` may have been authored for OmniVoice.
+ */
+export declare function resolveKokoroVoiceOrDefault(id: string): KokoroVoicePack;
+//# sourceMappingURL=voices.d.ts.map

package/src/services/voice/kokoro/voices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voices.d.ts","sourceRoot":"","sources":["voices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAO9D,OAAO,EACN,eAAe,EACf,uBAAuB,EACvB,kBAAkB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,qEAAqE;AACrE,wBAAgB,kBAAkB,IAAI,aAAa,CAAC,aAAa,CAAC,CAEjE;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,GACV,aAAa,CAAC,eAAe,CAAC,CAEhC;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACpC,GAAG,EAAE,MAAM,GACT,aAAa,CAAC,eAAe,CAAC,CAEhC;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAUvE"}

package/src/services/voice/kokoro/voices.ts

@@ -0,0 +1,64 @@
+/**
+ * Kokoro-82M voice catalog.
+ *
+ * Re-exports the bundled `KOKORO_VOICE_PACKS` table from `voice-presets.ts`
+ * under the canonical filename the integration spec calls out, and adds a few
+ * search helpers used by the runtime-selection layer and the picker UI.
+ *
+ * Each voice pack ships as a small (~256 fp32 values × 4 bytes ≈ 1 KB) style
+ * tensor under `<modelRoot>/voices/<file>`. Adding voices is cheap (download
+ * a single .bin), and a hot ONNX session can swap voices per-utterance with
+ * no re-init cost — the model is the same.
+ *
+ * Upstream registry: https://huggingface.co/hexgrad/Kokoro-82M/tree/main/voices
+ */
+
+import type { KokoroVoiceId, KokoroVoicePack } from "./types";
+import {
+	findKokoroVoice,
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_VOICE_PACKS,
+} from "./voice-presets";
+
+export {
+	findKokoroVoice,
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_VOICE_PACKS,
+} from "./voice-presets";
+
+/** All voice ids that ship with the upstream Kokoro v1.0 release. */
+export function listKokoroVoiceIds(): ReadonlyArray<KokoroVoiceId> {
+	return KOKORO_VOICE_PACKS.map((v) => v.id);
+}
+
+/** Filter voice packs by language tag (`a` US, `b` UK, etc.). */
+export function listKokoroVoicesByLang(
+	lang: string,
+): ReadonlyArray<KokoroVoicePack> {
+	return KOKORO_VOICE_PACKS.filter((v) => v.lang === lang);
+}
+
+/** Filter by an exact tag (`female`, `male`, `british`, `breathy`, ...). */
+export function listKokoroVoicesByTag(
+	tag: string,
+): ReadonlyArray<KokoroVoicePack> {
+	return KOKORO_VOICE_PACKS.filter((v) => v.tags?.includes(tag) === true);
+}
+
+/**
+ * Resolve a caller-supplied voice id against the registry. Returns the
+ * matching pack, or the default pack when the id is not bundled. Never
+ * throws — runtime selection treats this as a graceful fallback because the
+ * caller's `SpeakerPreset.voiceId` may have been authored for OmniVoice.
+ */
+export function resolveKokoroVoiceOrDefault(id: string): KokoroVoicePack {
+	const match = findKokoroVoice(id);
+	if (match) return match;
+	const fallback = findKokoroVoice(KOKORO_DEFAULT_VOICE_ID);
+	if (!fallback) {
+		throw new Error(
+			`[kokoro] default voice id ${KOKORO_DEFAULT_VOICE_ID} is missing from KOKORO_VOICE_PACKS — registry is corrupted`,
+		);
+	}
+	return fallback;
+}

package/src/services/voice/lifecycle.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Voice on/off state machine.
+ *
+ * Per `packages/inference/AGENTS.md` §4 + this scope's design goals,
+ * voice is OFF by default. Text + native MTP 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.
+ */
+import type { KernelSet, MmapRegionHandle, MtpDraftHandle, RefCountedResource, SchedulerSlot, SharedResourceRegistry, SharedTokenizer } from "./shared-resources";
+/**
+ * Discriminated union — never widened to `string`. Each state may carry
+ * payload (the `armed` payload includes the loaded mmap regions so the
+ * disarm path can call `evictPages()` on them).
+ */
+export type VoiceLifecycleState = {
+    readonly kind: "voice-off";
+} | {
+    readonly kind: "voice-arming";
+} | {
+    readonly kind: "voice-on";
+    readonly resources: ArmedResources;
+} | {
+    readonly kind: "voice-disarming";
+    readonly resources: ArmedResources;
+} | {
+    readonly kind: "voice-error";
+    readonly error: VoiceLifecycleError;
+};
+/**
+ * Resources held while voice is armed. Released in reverse order on
+ * disarm; the mmap regions get an explicit `evictPages()` call before
+ * `release()` so the OS reclaims pages even if the FFI keeps the file
+ * descriptor open for the next re-arm.
+ */
+export interface ArmedResources {
+    readonly tts: MmapRegionHandle;
+    readonly asr: MmapRegionHandle;
+    /** Speaker preset + phrase cache — kept in a small LRU after disarm. */
+    readonly voiceCaches: RefCountedResource;
+    /** Voice-specific scheduler nodes (chunker, rollback, ring buffer, barge-in). */
+    readonly voiceSchedulerNodes: RefCountedResource;
+}
+/**
+ * Resources held while text is up. Acquired by the engine when the
+ * bundle is activated; voice piggy-backs on these without re-loading.
+ */
+export interface TextResources {
+    readonly tokenizer: SharedTokenizer;
+    readonly textWeights: MmapRegionHandle;
+    readonly kernels: KernelSet;
+    readonly scheduler: SchedulerSlot;
+    readonly mtp: MtpDraftHandle;
+}
+/**
+ * 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 declare class VoiceLifecycleError extends Error {
+    readonly code: "ram-pressure" | "mmap-fail" | "kernel-missing" | "illegal-transition" | "arm-failed" | "disarm-failed";
+    constructor(code: VoiceLifecycleError["code"], message: string);
+}
+/**
+ * Loader functions injected at construction. Splitting these out keeps
+ * `VoiceLifecycle` independent of FFI specifics — the engine wires real
+ * loaders at runtime; tests inject mocks. Each loader MUST throw on
+ * failure (AGENTS.md §3 — no silent fallback).
+ */
+export interface VoiceLifecycleLoaders {
+    loadTtsRegion(): Promise<MmapRegionHandle>;
+    loadAsrRegion(): Promise<MmapRegionHandle>;
+    loadVoiceCaches(): Promise<RefCountedResource>;
+    loadVoiceSchedulerNodes(): Promise<RefCountedResource>;
+}
+export interface VoiceLifecycleEvents {
+    onTransition?(prev: VoiceLifecycleState, next: VoiceLifecycleState): void;
+}
+export declare class VoiceLifecycle {
+    private state;
+    private readonly registry;
+    private readonly loaders;
+    private readonly events;
+    constructor(args: {
+        registry: SharedResourceRegistry;
+        loaders: VoiceLifecycleLoaders;
+        events?: VoiceLifecycleEvents;
+    });
+    current(): VoiceLifecycleState;
+    /**
+     * 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.
+     */
+    arm(): Promise<ArmedResources>;
+    /**
+     * 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.
+     */
+    disarm(): Promise<void>;
+    /**
+     * 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(): void;
+    private transition;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/src/services/voice/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACX,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,EAAE,kBAAkB,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EACV,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,oBAAoB,GACpB,YAAY,GACZ,eAAe,CAAC;gBAEP,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAK9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACrC,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3C,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3C,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/C,uBAAuB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,oBAAoB;IACpC,YAAY,CAAC,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC1E;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;gBAElC,IAAI,EAAE;QACjB,QAAQ,EAAE,sBAAsB,CAAC;QACjC,OAAO,EAAE,qBAAqB,CAAC;QAC/B,MAAM,CAAC,EAAE,oBAAoB,CAAC;KAC9B;IAMD,OAAO,IAAI,mBAAmB;IAI9B;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC;IAqDpC;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAqD7B;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAUb,OAAO,CAAC,UAAU;CAKlB"}

package/src/services/voice/lifecycle.test.ts

@@ -0,0 +1,315 @@
+/**
+ * Voice lifecycle state-machine tests.
+ *
+ * Exercises every documented transition in `lifecycle.ts`:
+ *   - default state is `voice-off`
+ *   - `arm()` transitions through `voice-arming` → `voice-on`
+ *   - `disarm()` transitions through `voice-disarming` → `voice-off`
+ *     and invokes `evictPages()` on the TTS + ASR mmap regions
+ *   - illegal transitions throw `VoiceLifecycleError`
+ *   - 100x arm/disarm cycles do not leak refs in the registry
+ *   - mmap failure surfaces as `voice-error` with the right code,
+ *     not a silent fallback (AGENTS.md §3 + §9)
+ *   - `reset()` is the only way out of `voice-error`
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+	VoiceLifecycle,
+	VoiceLifecycleError,
+	type VoiceLifecycleLoaders,
+	type VoiceLifecycleState,
+} from "./lifecycle";
+import {
+	type MmapRegionHandle,
+	type RefCountedResource,
+	SharedResourceRegistry,
+} from "./shared-resources";
+
+interface FakeMmap extends MmapRegionHandle {
+	evictCalls: number;
+	releaseCalls: number;
+}
+
+function fakeMmap(id: string, opts: { evictThrows?: Error } = {}): FakeMmap {
+	const region: FakeMmap = {
+		id,
+		path: `/tmp/${id}`,
+		sizeBytes: 1024,
+		evictCalls: 0,
+		releaseCalls: 0,
+		async evictPages() {
+			region.evictCalls++;
+			if (opts.evictThrows) throw opts.evictThrows;
+		},
+		async release() {
+			region.releaseCalls++;
+		},
+	};
+	return region;
+}
+
+function fakeResource(
+	id: string,
+): RefCountedResource & { releaseCalls: number } {
+	const r = {
+		id,
+		releaseCalls: 0,
+		async release() {
+			r.releaseCalls++;
+		},
+	};
+	return r;
+}
+
+function loadersOk(): VoiceLifecycleLoaders & {
+	tts: FakeMmap;
+	asr: FakeMmap;
+	caches: ReturnType<typeof fakeResource>;
+	nodes: ReturnType<typeof fakeResource>;
+} {
+	const tts = fakeMmap("tts:omnivoice-default");
+	const asr = fakeMmap("asr:default");
+	const caches = fakeResource("voice-caches");
+	const nodes = fakeResource("voice-scheduler-nodes");
+	return {
+		tts,
+		asr,
+		caches,
+		nodes,
+		loadTtsRegion: async () => tts,
+		loadAsrRegion: async () => asr,
+		loadVoiceCaches: async () => caches,
+		loadVoiceSchedulerNodes: async () => nodes,
+	};
+}
+
+describe("VoiceLifecycle", () => {
+	it("defaults to voice-off", () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({ registry: reg, loaders: loadersOk() });
+		expect(lc.current().kind).toBe("voice-off");
+		expect(reg.size()).toBe(0);
+	});
+
+	it("arm() transitions voice-off → voice-arming → voice-on with all resources held", async () => {
+		const reg = new SharedResourceRegistry();
+		const loaders = loadersOk();
+		const transitions: VoiceLifecycleState["kind"][] = [];
+		const lc = new VoiceLifecycle({
+			registry: reg,
+			loaders,
+			events: {
+				onTransition: (_prev, next) => transitions.push(next.kind),
+			},
+		});
+		const armed = await lc.arm();
+		expect(transitions).toEqual(["voice-arming", "voice-on"]);
+		expect(lc.current().kind).toBe("voice-on");
+		expect(armed.tts.id).toBe(loaders.tts.id);
+		// All four resources tracked at refcount 1.
+		expect(reg.refCount(loaders.tts.id)).toBe(1);
+		expect(reg.refCount(loaders.asr.id)).toBe(1);
+		expect(reg.refCount(loaders.caches.id)).toBe(1);
+		expect(reg.refCount(loaders.nodes.id)).toBe(1);
+	});
+
+	it("disarm() transitions voice-on → voice-disarming → voice-off and invokes evictPages on tts+asr", async () => {
+		const reg = new SharedResourceRegistry();
+		const loaders = loadersOk();
+		const transitions: VoiceLifecycleState["kind"][] = [];
+		const lc = new VoiceLifecycle({
+			registry: reg,
+			loaders,
+			events: {
+				onTransition: (_prev, next) => transitions.push(next.kind),
+			},
+		});
+		await lc.arm();
+		transitions.length = 0;
+		await lc.disarm();
+		expect(transitions).toEqual(["voice-disarming", "voice-off"]);
+		expect(lc.current().kind).toBe("voice-off");
+		// madvise was called on both heavy regions.
+		expect(loaders.tts.evictCalls).toBe(1);
+		expect(loaders.asr.evictCalls).toBe(1);
+		// Underlying release ran for every resource.
+		expect(loaders.tts.releaseCalls).toBe(1);
+		expect(loaders.asr.releaseCalls).toBe(1);
+		expect(loaders.caches.releaseCalls).toBe(1);
+		expect(loaders.nodes.releaseCalls).toBe(1);
+		// Registry empty post-disarm.
+		expect(reg.size()).toBe(0);
+	});
+
+	it("arm() in voice-on throws illegal-transition", async () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({ registry: reg, loaders: loadersOk() });
+		await lc.arm();
+		let thrown: unknown;
+		try {
+			await lc.arm();
+		} catch (e) {
+			thrown = e;
+		}
+		expect(thrown).toBeInstanceOf(VoiceLifecycleError);
+		if (thrown instanceof VoiceLifecycleError) {
+			expect(thrown.code).toBe("illegal-transition");
+		}
+	});
+
+	it("disarm() in voice-off throws illegal-transition", async () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({ registry: reg, loaders: loadersOk() });
+		let thrown: unknown;
+		try {
+			await lc.disarm();
+		} catch (e) {
+			thrown = e;
+		}
+		expect(thrown).toBeInstanceOf(VoiceLifecycleError);
+		if (thrown instanceof VoiceLifecycleError) {
+			expect(thrown.code).toBe("illegal-transition");
+		}
+	});
+
+	it("100x arm/disarm cycles do not leak resources in the registry", async () => {
+		const reg = new SharedResourceRegistry();
+		// Build loaders that emit fresh handles on every call so refcount
+		// accounting actually exercises acquire/release rather than alias
+		// dedup.
+		let counter = 0;
+		const loaders: VoiceLifecycleLoaders = {
+			loadTtsRegion: async () => fakeMmap(`tts-${counter++}`),
+			loadAsrRegion: async () => fakeMmap(`asr-${counter++}`),
+			loadVoiceCaches: async () => fakeResource(`caches-${counter++}`),
+			loadVoiceSchedulerNodes: async () => fakeResource(`nodes-${counter++}`),
+		};
+		const lc = new VoiceLifecycle({ registry: reg, loaders });
+		for (let i = 0; i < 100; i++) {
+			await lc.arm();
+			await lc.disarm();
+		}
+		expect(lc.current().kind).toBe("voice-off");
+		expect(reg.size()).toBe(0);
+	});
+
+	it("simulated mmap failure surfaces as voice-error (no silent fallback)", async () => {
+		const reg = new SharedResourceRegistry();
+		const tts = fakeMmap("tts");
+		const ttsLoad = vi.fn(async () => tts);
+		const asrLoad = vi.fn(async () => {
+			throw new Error("mmap MAP_FAILED: cannot allocate memory");
+		});
+		const lc = new VoiceLifecycle({
+			registry: reg,
+			loaders: {
+				loadTtsRegion: ttsLoad,
+				loadAsrRegion: asrLoad,
+				loadVoiceCaches: async () => fakeResource("caches"),
+				loadVoiceSchedulerNodes: async () => fakeResource("nodes"),
+			},
+		});
+		let thrown: unknown;
+		try {
+			await lc.arm();
+		} catch (e) {
+			thrown = e;
+		}
+		expect(thrown).toBeInstanceOf(VoiceLifecycleError);
+		if (thrown instanceof VoiceLifecycleError) {
+			// The error message matched both /mmap|MAP_FAILED/ and
+			// /ENOMEM|out of memory|RAM/. The mmap branch comes second in the
+			// mapper — but the RAM regex matches "memory" first. Either is a
+			// structured code; the contract is "not silent fallback".
+			expect(["ram-pressure", "mmap-fail"]).toContain(thrown.code);
+		}
+		expect(lc.current().kind).toBe("voice-error");
+		// Partial acquisition rolled back — mapped pages are evicted first
+		// and registry refs are released.
+		expect(tts.evictCalls).toBe(1);
+		expect(reg.size()).toBe(0);
+	});
+
+	it("RAM-pressure error code is preferred when message says ENOMEM", async () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({
+			registry: reg,
+			loaders: {
+				loadTtsRegion: async () => {
+					throw new Error("ENOMEM: out of memory while mapping TTS weights");
+				},
+				loadAsrRegion: async () => fakeMmap("asr"),
+				loadVoiceCaches: async () => fakeResource("caches"),
+				loadVoiceSchedulerNodes: async () => fakeResource("nodes"),
+			},
+		});
+		let thrown: unknown;
+		try {
+			await lc.arm();
+		} catch (e) {
+			thrown = e;
+		}
+		expect(thrown).toBeInstanceOf(VoiceLifecycleError);
+		if (thrown instanceof VoiceLifecycleError) {
+			expect(thrown.code).toBe("ram-pressure");
+		}
+		expect(lc.current().kind).toBe("voice-error");
+	});
+
+	it("voice-error is terminal until reset()", async () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({
+			registry: reg,
+			loaders: {
+				loadTtsRegion: async () => {
+					throw new Error("kernel missing: turboquant_q4 unavailable");
+				},
+				loadAsrRegion: async () => fakeMmap("asr"),
+				loadVoiceCaches: async () => fakeResource("caches"),
+				loadVoiceSchedulerNodes: async () => fakeResource("nodes"),
+			},
+		});
+		await expect(lc.arm()).rejects.toBeInstanceOf(VoiceLifecycleError);
+		expect(lc.current().kind).toBe("voice-error");
+		// Cannot arm again from voice-error.
+		await expect(lc.arm()).rejects.toMatchObject({
+			code: "illegal-transition",
+		});
+		// Cannot disarm from voice-error.
+		await expect(lc.disarm()).rejects.toMatchObject({
+			code: "illegal-transition",
+		});
+		lc.reset();
+		expect(lc.current().kind).toBe("voice-off");
+	});
+
+	it("reset() in voice-off throws illegal-transition", () => {
+		const reg = new SharedResourceRegistry();
+		const lc = new VoiceLifecycle({ registry: reg, loaders: loadersOk() });
+		expect(() => lc.reset()).toThrow(VoiceLifecycleError);
+	});
+});
+
+describe("SharedResourceRegistry", () => {
+	it("dedupes by id and refcounts acquire/release", async () => {
+		const reg = new SharedResourceRegistry();
+		const a = fakeResource("foo");
+		const aliased = fakeResource("foo");
+		const first = reg.acquire(a);
+		const second = reg.acquire(aliased);
+		expect(second).toBe(first);
+		expect(reg.refCount("foo")).toBe(2);
+		await reg.release("foo");
+		expect(reg.refCount("foo")).toBe(1);
+		expect(a.releaseCalls).toBe(0);
+		await reg.release("foo");
+		expect(a.releaseCalls).toBe(1);
+		expect(reg.size()).toBe(0);
+	});
+
+	it("release of unknown id throws — no silent leak", async () => {
+		const reg = new SharedResourceRegistry();
+		await expect(reg.release("ghost")).rejects.toThrow(/unknown resource/);
+	});
+});