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

package/src/services/voice/shared-resources.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Cross-cut resource sharing between the text + voice surfaces of a
+ * single Eliza-1 bundle.
+ *
+ * Per `packages/inference/AGENTS.md` §4 ("shared KV cache scheduling,
+ * not shared KV memory" + "one process, one llama.cpp build, one GGML
+ * pin"), text and voice MUST share:
+ *   - the tokenizer (Eliza-1/OmniVoice share a vocabulary in this lineage),
+ *   - the mmap regions for weights (deduplicated by absolute path),
+ *   - the kernel set (same shipped llama.cpp library after fusion),
+ *   - the scheduler queue (one queue, prioritised),
+ *   - the native MTP draft path (always wired for Eliza-1).
+ *
+ * What they do NOT share:
+ *   - KV cache memory (different layer counts, different head configs,
+ *     different quantizations — separate caches, shared scheduler).
+ *
+ * This module owns reference counts on each shared resource and is the
+ * single arbiter of when a voice-only region can be released. It does
+ * NOT do any I/O itself — the actual mmap, madvise, or full model-unload
+ * behavior lives behind the `MmapRegionHandle` interface so platform
+ * bindings can choose the right memory policy.
+ */
+/** Minimal structural logger — keeps this module free of upstream deps. */
+interface Logger {
+    debug?(message: string): void;
+    warn?(message: string): void;
+    info?(message: string): void;
+}
+/**
+ * The model roles that can be resident at once on the local-inference
+ * path. The `MemoryMonitor` evicts them in *ascending priority* under RAM
+ * pressure (lowest first): low-cost voice auxiliaries are cheapest to drop,
+ * the text target is the last thing to go. Voice TTS/ASR weights are evicted
+ * via `MmapRegionHandle.evictPages()`; the embedding model is unloaded by
+ * its owner.
+ */
+export type ResidentModelRole = "drafter" | "emotion" | "speaker-id" | "vision" | "embedding" | "vad" | "asr" | "tts" | "text-target";
+/**
+ * Eviction priority by role — lower evicts first. Matches the brief's
+ * `emotion < speaker-id < vision/mmproj < embedding < vad < ASR <
+ * TTS < text-target`. The cold-3 set (`emotion`, `speaker-id`) is cheap to
+ * load on demand, so evicting them is the first reclamation step under
+ * sustained pressure. See `.swarm/research/R9-memory.md` §4.1.
+ */
+export declare const RESIDENT_ROLE_PRIORITY: Readonly<Record<ResidentModelRole, number>>;
+/**
+ * An evictable resident model role. The registry walks these in ascending
+ * `evictionPriority` under memory pressure and calls `evict()` until enough
+ * RAM has been reclaimed. `evict()` MUST be idempotent (a no-op when already
+ * evicted) and the role MUST re-load lazily on next use — the monitor only
+ * frees memory, it never re-loads.
+ */
+export interface EvictableModelRole extends RefCountedResource {
+    readonly role: ResidentModelRole;
+    /** Lower evicts first. Defaults to `RESIDENT_ROLE_PRIORITY[role]`. */
+    readonly evictionPriority: number;
+    /** True while the underlying weights/pages are still resident. */
+    isResident(): boolean;
+    /** Drop the resident weights/pages. Idempotent; re-loads lazily on demand. */
+    evict(): Promise<void>;
+    /** Best-effort estimate of RAM (MB) reclaimed by `evict()`. 0 when unknown. */
+    estimatedResidentMb(): number;
+}
+/**
+ * Build an `EvictableModelRole` from a role + an `evict` callback. `release()`
+ * defaults to a no-op (the registry's refcount, not `release`, gates eviction
+ * for these); pass one if the role owns disposable state. `estimatedMb` lets
+ * the monitor know roughly how much it will reclaim — pass 0 when unknown.
+ */
+export declare function createEvictableModelRole(args: {
+    id?: string;
+    role: ResidentModelRole;
+    evictionPriority?: number;
+    estimatedMb?: number;
+    isResident: () => boolean;
+    evict: () => Promise<void>;
+    release?: () => Promise<void>;
+}): EvictableModelRole;
+/**
+ * Anything ref-counted by the registry implements this. The caller of
+ * `release()` MUST guarantee that no further reads happen on the
+ * underlying resource — for mmap regions that means no kernel call has
+ * a pointer into the freed range.
+ */
+export interface RefCountedResource {
+    readonly id: string;
+    /** Released for real when the last ref drops. Idempotent. */
+    release(): Promise<void>;
+}
+/**
+ * mmap region handle. The fused omnivoice/llama.cpp build owns the real
+ * mmap call (it happens inside the FFI) — this interface is the JS-side
+ * proxy for it, so the lifecycle code can request page eviction without
+ * binding to a specific backend.
+ */
+export interface MmapRegionHandle extends RefCountedResource {
+    /** Absolute path of the file backing the mmap region. */
+    readonly path: string;
+    /** Byte size of the mapped region. */
+    readonly sizeBytes: number;
+    /**
+     * Release memory pressure for this region. Backends may implement this
+     * as a page hint or as a full voice-runtime unload. Common mappings:
+     *   - POSIX (Linux/Android/macOS-bg): `madvise(addr, len, MADV_DONTNEED)`
+     *   - macOS (foreground / iOS):        `madvise(addr, len, MADV_FREE_REUSABLE)`
+     *   - Windows:                         `VirtualUnlock` + `OfferVirtualMemory`
+     *
+     * The lifecycle test mocks this to assert the call happened.
+     */
+    evictPages(): Promise<void>;
+}
+/** Minimal tokenizer surface text + voice both consume. */
+export interface SharedTokenizer extends RefCountedResource {
+    readonly vocabSize: number;
+}
+/**
+ * Kernel set descriptor. The actual kernels are inside the fused
+ * llama.cpp build; this is the metadata the runtime reads at startup
+ * (AGENTS.md §3 #5: "the runtime MUST log the kernel set on startup").
+ */
+export interface KernelSet extends RefCountedResource {
+    readonly kernels: ReadonlyArray<string>;
+}
+/** Scheduler graph slot. One per active engine, refcounted by surface. */
+export interface SchedulerSlot extends RefCountedResource {
+    /** Surface (text/voice) currently holding a ref. */
+    surfaces(): ReadonlyArray<"text" | "voice">;
+}
+/** Native MTP draft state is shared between text-only and voice modes. */
+export interface MtpDraftHandle extends RefCountedResource {
+    readonly modelId: string;
+}
+export declare function createMtpDraftHandle(args: {
+    modelId: string;
+}): MtpDraftHandle;
+/**
+ * Owns the shared resources for one engine. Voice + text both `acquire`
+ * and `release` against the same registry; the registry only releases
+ * the underlying resource when refcount hits zero.
+ *
+ * Thread-safety: all methods run on the single Node event loop; no
+ * locks needed. Promises returned from `release()` MUST be awaited so
+ * the lifecycle state machine can observe completion.
+ */
+export declare class SharedResourceRegistry {
+    private readonly entries;
+    private readonly log?;
+    constructor(opts?: {
+        logger?: Logger;
+    });
+    /**
+     * Register a resource if absent, increment refcount otherwise. Returns
+     * the canonical instance — callers MUST use the returned value, not the
+     * one passed in, so a second registration with the same id resolves to
+     * the original (deduplication by id).
+     */
+    acquire<T extends RefCountedResource>(resource: T): T;
+    /**
+     * Decrement refcount; release the resource when it hits zero. Throws
+     * on unknown id — silent no-ops would hide leaks.
+     */
+    release(id: string): Promise<void>;
+    /** Diagnostic: current refcount, or 0 when not present. */
+    refCount(id: string): number;
+    /** Diagnostic: snapshot of currently-tracked resource ids. */
+    ids(): ReadonlyArray<string>;
+    /** Total tracked resources. */
+    size(): number;
+    /**
+     * Currently-resident evictable model roles, ascending by eviction
+     * priority (cheapest-to-evict first). Used by `MemoryMonitor` to walk
+     * roles under RAM pressure. Non-resident roles are filtered out — there's
+     * nothing to reclaim.
+     */
+    evictableRoles(): ReadonlyArray<EvictableModelRole>;
+    /**
+     * Evict the lowest-priority resident role and return its `id`, or `null`
+     * when nothing is evictable. Observable: emits an `info` log line so the
+     * eviction is visible in the dev console. The role re-loads lazily on
+     * next use — this only frees memory.
+     */
+    evictLowestPriorityRole(): Promise<{
+        id: string;
+        role: ResidentModelRole;
+        estimatedMb: number;
+    } | null>;
+}
+export {};
+//# sourceMappingURL=shared-resources.d.ts.map

package/src/services/voice/shared-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-resources.d.ts","sourceRoot":"","sources":["shared-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,2EAA2E;AAC3E,UAAU,MAAM;IACf,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAC1B,SAAS,GACT,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,KAAK,GACL,KAAK,GACL,KAAK,GACL,aAAa,CAAC;AAEjB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC5C,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAWjC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,UAAU,IAAI,OAAO,CAAC;IACtB,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,+EAA+E;IAC/E,mBAAmB,IAAI,MAAM,CAAC;CAC9B;AAeD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,GAAG,kBAAkB,CAkBrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC3D,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACxD,oDAAoD;IACpD,QAAQ,IAAI,aAAa,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;CAC5C;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAe,SAAQ,kBAAkB;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;CAChB,GAAG,cAAc,CAQjB;AAOD;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IACJ,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAS;gBAElB,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAI1C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,kBAAkB,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAUrD;;;OAGG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAI5B,8DAA8D;IAC9D,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC;IAI5B,+BAA+B;IAC/B,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,cAAc,IAAI,aAAa,CAAC,kBAAkB,CAAC;IAUnD;;;;;OAKG;IACG,uBAAuB,IAAI,OAAO,CAAC;QACxC,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,iBAAiB,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;CAUT"}

package/src/services/voice/shared-resources.ts

@@ -0,0 +1,320 @@
+/**
+ * Cross-cut resource sharing between the text + voice surfaces of a
+ * single Eliza-1 bundle.
+ *
+ * Per `packages/inference/AGENTS.md` §4 ("shared KV cache scheduling,
+ * not shared KV memory" + "one process, one llama.cpp build, one GGML
+ * pin"), text and voice MUST share:
+ *   - the tokenizer (Eliza-1/OmniVoice share a vocabulary in this lineage),
+ *   - the mmap regions for weights (deduplicated by absolute path),
+ *   - the kernel set (same shipped llama.cpp library after fusion),
+ *   - the scheduler queue (one queue, prioritised),
+ *   - the native MTP draft path (always wired for Eliza-1).
+ *
+ * What they do NOT share:
+ *   - KV cache memory (different layer counts, different head configs,
+ *     different quantizations — separate caches, shared scheduler).
+ *
+ * This module owns reference counts on each shared resource and is the
+ * single arbiter of when a voice-only region can be released. It does
+ * NOT do any I/O itself — the actual mmap, madvise, or full model-unload
+ * behavior lives behind the `MmapRegionHandle` interface so platform
+ * bindings can choose the right memory policy.
+ */
+
+/** Minimal structural logger — keeps this module free of upstream deps. */
+interface Logger {
+	debug?(message: string): void;
+	warn?(message: string): void;
+	info?(message: string): void;
+}
+
+/**
+ * The model roles that can be resident at once on the local-inference
+ * path. The `MemoryMonitor` evicts them in *ascending priority* under RAM
+ * pressure (lowest first): low-cost voice auxiliaries are cheapest to drop,
+ * the text target is the last thing to go. Voice TTS/ASR weights are evicted
+ * via `MmapRegionHandle.evictPages()`; the embedding model is unloaded by
+ * its owner.
+ */
+export type ResidentModelRole =
+	| "drafter"
+	| "emotion"
+	| "speaker-id"
+	| "vision"
+	| "embedding"
+	| "vad"
+	| "asr"
+	| "tts"
+	| "text-target";
+
+/**
+ * Eviction priority by role — lower evicts first. Matches the brief's
+ * `emotion < speaker-id < vision/mmproj < embedding < vad < ASR <
+ * TTS < text-target`. The cold-3 set (`emotion`, `speaker-id`) is cheap to
+ * load on demand, so evicting them is the first reclamation step under
+ * sustained pressure. See `.swarm/research/R9-memory.md` §4.1.
+ */
+export const RESIDENT_ROLE_PRIORITY: Readonly<
+	Record<ResidentModelRole, number>
+> = {
+	drafter: 10,
+	emotion: 15,
+	"speaker-id": 18,
+	vision: 20,
+	embedding: 25,
+	vad: 35,
+	asr: 40,
+	tts: 50,
+	"text-target": 100,
+};
+
+/**
+ * An evictable resident model role. The registry walks these in ascending
+ * `evictionPriority` under memory pressure and calls `evict()` until enough
+ * RAM has been reclaimed. `evict()` MUST be idempotent (a no-op when already
+ * evicted) and the role MUST re-load lazily on next use — the monitor only
+ * frees memory, it never re-loads.
+ */
+export interface EvictableModelRole extends RefCountedResource {
+	readonly role: ResidentModelRole;
+	/** Lower evicts first. Defaults to `RESIDENT_ROLE_PRIORITY[role]`. */
+	readonly evictionPriority: number;
+	/** True while the underlying weights/pages are still resident. */
+	isResident(): boolean;
+	/** Drop the resident weights/pages. Idempotent; re-loads lazily on demand. */
+	evict(): Promise<void>;
+	/** Best-effort estimate of RAM (MB) reclaimed by `evict()`. 0 when unknown. */
+	estimatedResidentMb(): number;
+}
+
+function isEvictableModelRole(
+	value: RefCountedResource,
+): value is EvictableModelRole {
+	const candidate = value as Partial<EvictableModelRole>;
+	return (
+		typeof candidate.role === "string" &&
+		typeof candidate.evictionPriority === "number" &&
+		typeof candidate.isResident === "function" &&
+		typeof candidate.evict === "function" &&
+		typeof candidate.estimatedResidentMb === "function"
+	);
+}
+
+/**
+ * Build an `EvictableModelRole` from a role + an `evict` callback. `release()`
+ * defaults to a no-op (the registry's refcount, not `release`, gates eviction
+ * for these); pass one if the role owns disposable state. `estimatedMb` lets
+ * the monitor know roughly how much it will reclaim — pass 0 when unknown.
+ */
+export function createEvictableModelRole(args: {
+	id?: string;
+	role: ResidentModelRole;
+	evictionPriority?: number;
+	estimatedMb?: number;
+	isResident: () => boolean;
+	evict: () => Promise<void>;
+	release?: () => Promise<void>;
+}): EvictableModelRole {
+	const id = args.id ?? `model-role:${args.role}`;
+	const priority = args.evictionPriority ?? RESIDENT_ROLE_PRIORITY[args.role];
+	const estimatedMb = args.estimatedMb ?? 0;
+	return {
+		id,
+		role: args.role,
+		evictionPriority: priority,
+		isResident: args.isResident,
+		estimatedResidentMb: () => (args.isResident() ? estimatedMb : 0),
+		async evict(): Promise<void> {
+			if (!args.isResident()) return;
+			await args.evict();
+		},
+		async release(): Promise<void> {
+			await args.release?.();
+		},
+	};
+}
+
+/**
+ * Anything ref-counted by the registry implements this. The caller of
+ * `release()` MUST guarantee that no further reads happen on the
+ * underlying resource — for mmap regions that means no kernel call has
+ * a pointer into the freed range.
+ */
+export interface RefCountedResource {
+	readonly id: string;
+	/** Released for real when the last ref drops. Idempotent. */
+	release(): Promise<void>;
+}
+
+/**
+ * mmap region handle. The fused omnivoice/llama.cpp build owns the real
+ * mmap call (it happens inside the FFI) — this interface is the JS-side
+ * proxy for it, so the lifecycle code can request page eviction without
+ * binding to a specific backend.
+ */
+export interface MmapRegionHandle extends RefCountedResource {
+	/** Absolute path of the file backing the mmap region. */
+	readonly path: string;
+	/** Byte size of the mapped region. */
+	readonly sizeBytes: number;
+	/**
+	 * Release memory pressure for this region. Backends may implement this
+	 * as a page hint or as a full voice-runtime unload. Common mappings:
+	 *   - POSIX (Linux/Android/macOS-bg): `madvise(addr, len, MADV_DONTNEED)`
+	 *   - macOS (foreground / iOS):        `madvise(addr, len, MADV_FREE_REUSABLE)`
+	 *   - Windows:                         `VirtualUnlock` + `OfferVirtualMemory`
+	 *
+	 * The lifecycle test mocks this to assert the call happened.
+	 */
+	evictPages(): Promise<void>;
+}
+
+/** Minimal tokenizer surface text + voice both consume. */
+export interface SharedTokenizer extends RefCountedResource {
+	readonly vocabSize: number;
+}
+
+/**
+ * Kernel set descriptor. The actual kernels are inside the fused
+ * llama.cpp build; this is the metadata the runtime reads at startup
+ * (AGENTS.md §3 #5: "the runtime MUST log the kernel set on startup").
+ */
+export interface KernelSet extends RefCountedResource {
+	readonly kernels: ReadonlyArray<string>;
+}
+
+/** Scheduler graph slot. One per active engine, refcounted by surface. */
+export interface SchedulerSlot extends RefCountedResource {
+	/** Surface (text/voice) currently holding a ref. */
+	surfaces(): ReadonlyArray<"text" | "voice">;
+}
+
+/** Native MTP draft state is shared between text-only and voice modes. */
+export interface MtpDraftHandle extends RefCountedResource {
+	readonly modelId: string;
+}
+
+export function createMtpDraftHandle(args: {
+	modelId: string;
+}): MtpDraftHandle {
+	return {
+		id: `mtp:${args.modelId}`,
+		modelId: args.modelId,
+		async release(): Promise<void> {
+			// MTP state lifetime is owned by the active native text runtime.
+		},
+	};
+}
+
+interface RegistryEntry<T extends RefCountedResource> {
+	readonly resource: T;
+	refCount: number;
+}
+
+/**
+ * Owns the shared resources for one engine. Voice + text both `acquire`
+ * and `release` against the same registry; the registry only releases
+ * the underlying resource when refcount hits zero.
+ *
+ * Thread-safety: all methods run on the single Node event loop; no
+ * locks needed. Promises returned from `release()` MUST be awaited so
+ * the lifecycle state machine can observe completion.
+ */
+export class SharedResourceRegistry {
+	private readonly entries = new Map<
+		string,
+		RegistryEntry<RefCountedResource>
+	>();
+	private readonly log?: Logger;
+
+	constructor(opts: { logger?: Logger } = {}) {
+		this.log = opts.logger;
+	}
+
+	/**
+	 * Register a resource if absent, increment refcount otherwise. Returns
+	 * the canonical instance — callers MUST use the returned value, not the
+	 * one passed in, so a second registration with the same id resolves to
+	 * the original (deduplication by id).
+	 */
+	acquire<T extends RefCountedResource>(resource: T): T {
+		const existing = this.entries.get(resource.id);
+		if (existing) {
+			existing.refCount++;
+			return existing.resource as T;
+		}
+		this.entries.set(resource.id, { resource, refCount: 1 });
+		return resource;
+	}
+
+	/**
+	 * Decrement refcount; release the resource when it hits zero. Throws
+	 * on unknown id — silent no-ops would hide leaks.
+	 */
+	async release(id: string): Promise<void> {
+		const entry = this.entries.get(id);
+		if (!entry) {
+			throw new Error(
+				`[shared-resources] release(${id}): unknown resource — possible double release or registry desync`,
+			);
+		}
+		entry.refCount--;
+		if (entry.refCount > 0) return;
+		this.entries.delete(id);
+		await entry.resource.release();
+		this.log?.debug?.(`[SharedResourceRegistry] released ${id}`);
+	}
+
+	/** Diagnostic: current refcount, or 0 when not present. */
+	refCount(id: string): number {
+		return this.entries.get(id)?.refCount ?? 0;
+	}
+
+	/** Diagnostic: snapshot of currently-tracked resource ids. */
+	ids(): ReadonlyArray<string> {
+		return Array.from(this.entries.keys());
+	}
+
+	/** Total tracked resources. */
+	size(): number {
+		return this.entries.size;
+	}
+
+	/**
+	 * Currently-resident evictable model roles, ascending by eviction
+	 * priority (cheapest-to-evict first). Used by `MemoryMonitor` to walk
+	 * roles under RAM pressure. Non-resident roles are filtered out — there's
+	 * nothing to reclaim.
+	 */
+	evictableRoles(): ReadonlyArray<EvictableModelRole> {
+		const out: EvictableModelRole[] = [];
+		for (const entry of this.entries.values()) {
+			if (isEvictableModelRole(entry.resource) && entry.resource.isResident()) {
+				out.push(entry.resource);
+			}
+		}
+		return out.sort((a, b) => a.evictionPriority - b.evictionPriority);
+	}
+
+	/**
+	 * Evict the lowest-priority resident role and return its `id`, or `null`
+	 * when nothing is evictable. Observable: emits an `info` log line so the
+	 * eviction is visible in the dev console. The role re-loads lazily on
+	 * next use — this only frees memory.
+	 */
+	async evictLowestPriorityRole(): Promise<{
+		id: string;
+		role: ResidentModelRole;
+		estimatedMb: number;
+	} | null> {
+		const [target] = this.evictableRoles();
+		if (!target) return null;
+		const estimatedMb = target.estimatedResidentMb();
+		await target.evict();
+		this.log?.info?.(
+			`[SharedResourceRegistry] evicted role ${target.role} (${target.id}); reclaimed ~${estimatedMb} MB`,
+		);
+		return { id: target.id, role: target.role, estimatedMb };
+	}
+}

package/src/services/voice/speaker/attribution-pipeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Speaker-ID + diarization attribution pipeline.
+ *
+ * Wraps a `StreamingTranscriber` so the partial / final
+ * `TranscriptUpdate`s carry diarized `VoiceSegment[]` and a
+ * `primarySpeaker`. The attribution runs in parallel with ASR — the
+ * encoder fires the moment ≥ 1 s of audio is available, and the
+ * profile store's `beginMatch` starts at speech-start.
+ *
+ * This module owns *only* the attribution logic. It does NOT replace
+ * the transcriber; callers feed PCM through both the transcriber and
+ * the attributor in parallel, then attach the resolved metadata via
+ * `BaseStreamingTranscriber.setMetadataDefaults()` once it lands.
+ *
+ * Why a separate module: the existing `VoicePipeline` is large and
+ * already handles a lot. Putting attribution behind a small adapter
+ * lets the voice pipeline opt in without entangling the diarizer /
+ * encoder / profile-store dependencies into the streaming-ASR contract.
+ */
+import type { VoiceProfileObservation, VoiceProfileStore } from "../profile-store";
+import type { VoiceInputSource, VoiceSegment, VoiceSpeaker, VoiceTurnMetadata } from "../types";
+import type { Diarizer } from "./diarizer";
+import type { SpeakerEncoder } from "./encoder";
+export interface VoiceAttributionPipelineDeps {
+    encoder: SpeakerEncoder;
+    diarizer?: Diarizer;
+    profileStore: VoiceProfileStore;
+}
+export interface VoiceAttributionRequest {
+    turnId: string;
+    source?: VoiceInputSource;
+    /** Concatenated mono 16 kHz PCM for the entire turn. */
+    pcm: Float32Array;
+    startedAtMs?: number;
+    endedAtMs?: number;
+    /** When set, the attributor will only run if the abort signal isn't yet fired. */
+    signal?: AbortSignal;
+}
+export interface VoiceAttributionOutput {
+    turnId: string;
+    primarySpeaker?: VoiceSpeaker;
+    segments: VoiceSegment[];
+    turn: VoiceTurnMetadata;
+    observation: VoiceProfileObservation | null;
+}
+/**
+ * Run the diarizer + encoder + profile-store against a complete turn's
+ * audio. The caller is responsible for slicing the audio buffer (the
+ * pipeline's prefix queue already buffers the entire utterance for
+ * the streaming-ASR path).
+ *
+ * The high-level flow:
+ *   1. Diarizer runs on the full PCM, producing per-segment speaker
+ *      tags (window-local ids).
+ *   2. We pick the longest local-speaker span and run the encoder on
+ *      that span (≥ 1 s) to produce a 256-dim embedding.
+ *   3. The embedding is matched against the profile store. On hit,
+ *      attribute the turn to the matched profile's entity. On miss,
+ *      create a new cluster profile (no entity binding — that happens
+ *      at the LifeOps layer based on utterance text).
+ *   4. Build `VoiceSegment[]` with the resolved speaker, plus a
+ *      `VoiceTurnMetadata` for downstream consumers.
+ */
+export declare class VoiceAttributionPipeline {
+    private readonly deps;
+    constructor(deps: VoiceAttributionPipelineDeps);
+    attribute(req: VoiceAttributionRequest): Promise<VoiceAttributionOutput>;
+    private buildEmptyOutput;
+    private spliceSpans;
+    private spanMsTotal;
+    private localToVoiceSegments;
+    private localToUnknownSegments;
+}
+//# sourceMappingURL=attribution-pipeline.d.ts.map

package/src/services/voice/speaker/attribution-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-pipeline.d.ts","sourceRoot":"","sources":["attribution-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACX,uBAAuB,EACvB,iBAAiB,EACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,QAAQ,EAAuB,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,MAAM,WAAW,4BAA4B;IAC5C,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,EAAE,iBAAiB,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,wDAAwD;IACxD,GAAG,EAAE,YAAY,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAC5C;AAgCD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,wBAAwB;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,4BAA4B;IAEzD,SAAS,CACd,GAAG,EAAE,uBAAuB,GAC1B,OAAO,CAAC,sBAAsB,CAAC;IA2KlC,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,oBAAoB;IAwC5B,OAAO,CAAC,sBAAsB;CAc9B"}