@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/handler-registry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Side-registry of model handlers registered on an AgentRuntime.
+ *
+ * The elizaOS core exposes `runtime.registerModel(type, handler, provider,
+ * priority)` but no way to list who registered what. This module intercepts
+ * `registerModel` at runtime to record every registration in a Map keyed by
+ * model type, plus fires status listeners so the UI can render a live
+ * [ModelType × Provider] routing table.
+ *
+ * Because we monkey-patch `registerModel` we also keep the original
+ * handler reference — the router-handler (see `router-handler.ts`) uses
+ * this to dispatch inference calls by policy without going through
+ * `runtime.useModel` (which would loop back to us and recurse).
+ */
+import { AgentRuntime, type IAgentRuntime } from "@elizaos/core";
+export interface HandlerRegistration {
+    modelType: string;
+    provider: string;
+    priority: number;
+    registeredAt: string;
+    /**
+     * The original handler function. Captured so the router-handler can
+     * dispatch to it directly, bypassing `runtime.useModel` which would
+     * re-enter the router itself.
+     */
+    handler: (runtime: IAgentRuntime, params: Record<string, unknown>) => Promise<unknown>;
+}
+type Listener = (registrations: HandlerRegistration[]) => void;
+declare class HandlerRegistry {
+    private readonly registrations;
+    private readonly listeners;
+    private installedOn;
+    /**
+     * Snapshot of all registrations grouped by model type, sorted by
+     * priority descending inside each group (matches core's selection
+     * order). Callers must not mutate the returned array.
+     */
+    getAll(): HandlerRegistration[];
+    /** All registrations for a given model type, sorted by priority desc. */
+    getForType(modelType: string): HandlerRegistration[];
+    /**
+     * Registrations excluding a specific provider. Used by the router-handler
+     * to find "all providers except me" when dispatching.
+     */
+    getForTypeExcluding(modelType: string, excludeProvider: string): HandlerRegistration[];
+    subscribe(listener: Listener): () => void;
+    private emit;
+    private record;
+    /**
+     * Install the interception on a runtime. Idempotent per runtime instance.
+     * For most boot paths the prototype-level patch below already covers the
+     * runtime before any plugin registers; this method is the belt-and-braces
+     * fallback for runtimes constructed before the patch ran.
+     */
+    installOn(runtime: AgentRuntime): void;
+    /** Exposed so the prototype patch can record through the singleton. */
+    recordFromPrototype(reg: HandlerRegistration): void;
+}
+export declare const handlerRegistry: HandlerRegistry;
+/**
+ * Public type used by the API/UI — omits the handler function for
+ * serialisation and to prevent UI code from accidentally calling it.
+ */
+export interface PublicRegistration {
+    modelType: string;
+    provider: string;
+    priority: number;
+    registeredAt: string;
+}
+export declare function toPublicRegistration(reg: HandlerRegistration): PublicRegistration;
+export {};
+//# sourceMappingURL=handler-registry.d.ts.map

package/src/services/handler-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-registry.d.ts","sourceRoot":"","sources":["handler-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,CACR,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,KAAK,QAAQ,GAAG,CAAC,aAAa,EAAE,mBAAmB,EAAE,KAAK,IAAI,CAAC;AAE/D,cAAM,eAAe;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,WAAW,CAAkC;IAErD;;;;OAIG;IACH,MAAM,IAAI,mBAAmB,EAAE;IAQ/B,yEAAyE;IACzE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAKpD;;;OAGG;IACH,mBAAmB,CAClB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACrB,mBAAmB,EAAE;IAMxB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI;IAOzC,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,MAAM;IAYd;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IA2CtC,uEAAuE;IACvE,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;CAGnD;AA8DD,eAAO,MAAM,eAAe,iBAAwB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,mBAAmB,GACtB,kBAAkB,CAOpB"}

package/src/services/handler-registry.ts

@@ -0,0 +1,240 @@
+/**
+ * Side-registry of model handlers registered on an AgentRuntime.
+ *
+ * The elizaOS core exposes `runtime.registerModel(type, handler, provider,
+ * priority)` but no way to list who registered what. This module intercepts
+ * `registerModel` at runtime to record every registration in a Map keyed by
+ * model type, plus fires status listeners so the UI can render a live
+ * [ModelType × Provider] routing table.
+ *
+ * Because we monkey-patch `registerModel` we also keep the original
+ * handler reference — the router-handler (see `router-handler.ts`) uses
+ * this to dispatch inference calls by policy without going through
+ * `runtime.useModel` (which would loop back to us and recurse).
+ */
+
+import { AgentRuntime, type IAgentRuntime } from "@elizaos/core";
+
+export interface HandlerRegistration {
+	modelType: string;
+	provider: string;
+	priority: number;
+	registeredAt: string;
+	/**
+	 * The original handler function. Captured so the router-handler can
+	 * dispatch to it directly, bypassing `runtime.useModel` which would
+	 * re-enter the router itself.
+	 */
+	handler: (
+		runtime: IAgentRuntime,
+		params: Record<string, unknown>,
+	) => Promise<unknown>;
+}
+
+type Listener = (registrations: HandlerRegistration[]) => void;
+
+class HandlerRegistry {
+	private readonly registrations = new Map<string, HandlerRegistration[]>();
+	private readonly listeners = new Set<Listener>();
+	private installedOn: WeakSet<object> = new WeakSet();
+
+	/**
+	 * Snapshot of all registrations grouped by model type, sorted by
+	 * priority descending inside each group (matches core's selection
+	 * order). Callers must not mutate the returned array.
+	 */
+	getAll(): HandlerRegistration[] {
+		const out: HandlerRegistration[] = [];
+		for (const list of this.registrations.values()) {
+			out.push(...list);
+		}
+		return out;
+	}
+
+	/** All registrations for a given model type, sorted by priority desc. */
+	getForType(modelType: string): HandlerRegistration[] {
+		const list = this.registrations.get(modelType);
+		return list ? [...list] : [];
+	}
+
+	/**
+	 * Registrations excluding a specific provider. Used by the router-handler
+	 * to find "all providers except me" when dispatching.
+	 */
+	getForTypeExcluding(
+		modelType: string,
+		excludeProvider: string,
+	): HandlerRegistration[] {
+		return this.getForType(modelType).filter(
+			(r) => r.provider !== excludeProvider,
+		);
+	}
+
+	subscribe(listener: Listener): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	private emit(): void {
+		const snapshot = this.getAll();
+		for (const listener of this.listeners) {
+			try {
+				listener(snapshot);
+			} catch {
+				this.listeners.delete(listener);
+			}
+		}
+	}
+
+	private record(reg: HandlerRegistration): void {
+		const existing = this.registrations.get(reg.modelType) ?? [];
+		// Replace any prior registration from the same provider for this
+		// model type. Core allows multiple providers per type but only one
+		// registration per (type, provider) pair — last write wins.
+		const filtered = existing.filter((r) => r.provider !== reg.provider);
+		filtered.push(reg);
+		filtered.sort((a, b) => b.priority - a.priority);
+		this.registrations.set(reg.modelType, filtered);
+		this.emit();
+	}
+
+	/**
+	 * Install the interception on a runtime. Idempotent per runtime instance.
+	 * For most boot paths the prototype-level patch below already covers the
+	 * runtime before any plugin registers; this method is the belt-and-braces
+	 * fallback for runtimes constructed before the patch ran.
+	 */
+	installOn(runtime: AgentRuntime): void {
+		installPrototypePatch();
+		const rt = runtime as AgentRuntime & {
+			registerModel?: unknown;
+		};
+		if (typeof rt.registerModel !== "function") return;
+		if (this.installedOn.has(rt)) return;
+		this.installedOn.add(rt);
+
+		// If the runtime already inherited the patched prototype method the
+		// prototype handles every call. Nothing to do per-instance.
+		const protoMethod = Object.getPrototypeOf(rt)?.registerModel as
+			| PatchMarkedRegisterModel
+			| undefined;
+		if (protoMethod?.[PATCH_MARK]) {
+			return;
+		}
+
+		// Per-instance wrap only for legacy runtimes whose prototype pre-dates
+		// our prototype patch (shouldn't happen in practice).
+		const original = rt.registerModel.bind(runtime) as (
+			modelType: string,
+			handler: HandlerRegistration["handler"],
+			provider: string,
+			priority?: number,
+		) => void;
+		rt.registerModel = ((
+			modelType: string,
+			handler: HandlerRegistration["handler"],
+			provider: string,
+			priority?: number,
+		) => {
+			this.record({
+				modelType: String(modelType),
+				provider: String(provider),
+				priority: typeof priority === "number" ? priority : 0,
+				registeredAt: new Date().toISOString(),
+				handler,
+			});
+			return original(modelType, handler, provider, priority);
+		}) as typeof rt.registerModel;
+	}
+
+	/** Exposed so the prototype patch can record through the singleton. */
+	recordFromPrototype(reg: HandlerRegistration): void {
+		this.record(reg);
+	}
+}
+
+const PATCH_MARK = Symbol.for("eliza.local-inference.registerModel.patched");
+let prototypePatched = false;
+
+type RegisterModelMethod = (
+	this: AgentRuntime,
+	modelType: string,
+	handler: HandlerRegistration["handler"],
+	provider: string,
+	priority?: number,
+) => void;
+
+type PatchMarkedRegisterModel = RegisterModelMethod & {
+	[PATCH_MARK]?: true;
+};
+
+/**
+ * One-shot patch of `AgentRuntime.prototype.registerModel` so every runtime
+ * instance — including ones constructed later in boot — records through
+ * the singleton handler registry. Idempotent.
+ */
+function installPrototypePatch(): void {
+	if (prototypePatched) return;
+	const proto = AgentRuntime.prototype as AgentRuntime & {
+		registerModel: RegisterModelMethod;
+	};
+	const original = proto.registerModel;
+	if (typeof original !== "function") return;
+	if ((original as PatchMarkedRegisterModel)[PATCH_MARK]) {
+		prototypePatched = true;
+		return;
+	}
+	const patched = function patchedRegisterModel(
+		this: AgentRuntime,
+		modelType: string,
+		handler: HandlerRegistration["handler"],
+		provider: string,
+		priority?: number,
+	): void {
+		try {
+			handlerRegistry.recordFromPrototype({
+				modelType: String(modelType),
+				provider: String(provider),
+				priority: typeof priority === "number" ? priority : 0,
+				registeredAt: new Date().toISOString(),
+				handler,
+			});
+		} catch {
+			// Never let registry bookkeeping break the registration path.
+		}
+		original.call(this, modelType, handler, provider, priority);
+	} as typeof original & { [PATCH_MARK]?: true };
+	patched[PATCH_MARK] = true;
+	proto.registerModel = patched;
+	prototypePatched = true;
+}
+
+// Install at module-import time. This is a process-wide side effect but a
+// benign one: the patch is idempotent and forwards to the original.
+installPrototypePatch();
+
+export const handlerRegistry = new HandlerRegistry();
+
+/**
+ * Public type used by the API/UI — omits the handler function for
+ * serialisation and to prevent UI code from accidentally calling it.
+ */
+export interface PublicRegistration {
+	modelType: string;
+	provider: string;
+	priority: number;
+	registeredAt: string;
+}
+
+export function toPublicRegistration(
+	reg: HandlerRegistration,
+): PublicRegistration {
+	return {
+		modelType: reg.modelType,
+		provider: reg.provider,
+		priority: reg.priority,
+		registeredAt: reg.registeredAt,
+	};
+}

package/src/services/hardware.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Hardware probe for local inference sizing.
+ *
+ * Uses `capacitor-llama` when available to read GPU backend + VRAM. Falls back
+ * to Node's `os` module when the binding isn't installed — we don't require
+ * the plugin to be loaded for the probe endpoint to return useful data.
+ *
+ * Dynamic import is intentional: the binding pulls a native prebuilt that we
+ * don't want eagerly required at module-load time (breaks CI environments
+ * without the trusted-dependency flag).
+ */
+import type { Eliza1DeviceCaps } from "./manifest";
+import type { CpuFeatureProbe, HardwareProbe, OpenVinoHardwareProbe } from "./types";
+interface CpuFeatureDetectionHost {
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+    readFileSync?: (path: string, encoding: BufferEncoding) => string;
+    execFileSync?: (file: string, args: readonly string[], options: {
+        encoding: BufferEncoding;
+        stdio: "pipe";
+    }) => string;
+}
+export declare function detectCpuFeatures(host?: CpuFeatureDetectionHost): CpuFeatureProbe | undefined;
+export declare function hasUsableArmCpuBackend(probe: HardwareProbe): boolean;
+interface OpenVinoDetectionHost {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    existsSync?: (path: string) => boolean;
+    readdirSync?: (path: string) => string[];
+}
+export declare function detectOpenVinoDevices(host?: OpenVinoDetectionHost): OpenVinoHardwareProbe;
+/**
+ * Read current system + GPU state. Cheap enough to call per-request; no
+ * internal caching so the UI always reflects live VRAM usage.
+ */
+export declare function probeHardware(): Promise<HardwareProbe>;
+/**
+ * Map a hardware probe onto the Eliza-1 device-capability snapshot used by
+ * the manifest validator and the bundle downloader.
+ *
+ * Backends: `cpu` is always present (the floor). A detected GPU backend is
+ * added when `capacitor-llama` reports one (`metal` on Apple Silicon, `cuda`
+ * on NVIDIA, `vulkan` on cross-vendor Linux/Android). We do not synthesize
+ * `rocm` from the probe — `capacitor-llama` reports AMD as `vulkan` on the
+ * builds we ship, and a bundle that only verified ROCm but not Vulkan is
+ * legitimately not installable here.
+ *
+ * `ramMb` is total system RAM. On Apple Silicon that is also the GPU's
+ * working memory; on discrete-GPU boxes the recommendation engine layers
+ * its own VRAM-vs-RAM heuristics on top, but the bundle's `ramBudgetMb.min`
+ * is a system-RAM floor in every manifest.
+ */
+export declare function deviceCapsFromProbe(probe: HardwareProbe): Eliza1DeviceCaps;
+/**
+ * Compatibility assessment for a specific model given current hardware.
+ *
+ * Green/fits: comfortable headroom (model < 70% of effective memory).
+ * Yellow/tight: will run but may swap or stutter under load.
+ * Red/wontfit: exceeds available memory.
+ */
+export declare function assessFit(probe: HardwareProbe, modelSizeGb: number, minRamGb: number): "fits" | "tight" | "wontfit";
+export {};
+//# sourceMappingURL=hardware.d.ts.map

package/src/services/hardware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardware.d.ts","sourceRoot":"","sources":["hardware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EACX,eAAe,EACf,aAAa,EAGb,qBAAqB,EACrB,MAAM,SAAS,CAAC;AA+BjB,UAAU,uBAAuB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC;IAC3B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,MAAM,CAAC;IAClE,YAAY,CAAC,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAChD,MAAM,CAAC;CACZ;AAmCD,wBAAgB,iBAAiB,CAChC,IAAI,GAAE,uBAA4B,GAChC,eAAe,GAAG,SAAS,CA+C7B;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAGpE;AAiCD,UAAU,qBAAqB;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;CACzC;AAoCD,wBAAgB,qBAAqB,CACpC,IAAI,GAAE,qBAA0B,GAC9B,qBAAqB,CAgFvB;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CA+B5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAiB1E;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACd,MAAM,GAAG,OAAO,GAAG,SAAS,CAW9B"}

package/src/services/hardware.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import {
+	detectCpuFeatures,
+	detectOpenVinoDevices,
+	deviceCapsFromProbe,
+} from "./hardware";
+
+function detector(files: Record<string, string[] | true>) {
+	const existsSync = (path: string): boolean => path in files;
+	const readdirSync = (path: string): string[] => {
+		const value = files[path];
+		return Array.isArray(value) ? value : [];
+	};
+	return { existsSync, readdirSync };
+}
+
+describe("detectOpenVinoDevices", () => {
+	it("prefers NPU for ASR when OpenVINO runtime and accel node are present", () => {
+		const probe = detectOpenVinoDevices({
+			platform: "linux",
+			env: { OpenVINO_DIR: "/opt/intel/openvino_2026/runtime/cmake" },
+			...detector({
+				"/dev/accel": ["accel0"],
+			}),
+		});
+
+		expect(probe.runtimeAvailable).toBe(true);
+		expect(probe.devices).toEqual(["CPU", "NPU"]);
+		expect(probe.npu.accelNodes).toEqual(["/dev/accel/accel0"]);
+		expect(probe.recommendedAsrDevice).toBe("NPU");
+	});
+
+	it("warns when Intel render nodes exist without the Compute Runtime stack", () => {
+		const probe = detectOpenVinoDevices({
+			platform: "linux",
+			env: { OpenVINO_DIR: "/opt/intel/openvino_2026/runtime/cmake" },
+			...detector({
+				"/dev/dri": ["card0", "renderD128"],
+			}),
+		});
+
+		expect(probe.devices).toEqual(["CPU"]);
+		expect(probe.gpu.renderNodes).toEqual(["/dev/dri/renderD128"]);
+		expect(probe.gpu.computeRuntimeReady).toBe(false);
+		expect(probe.gpu.missingLinuxPackages).toEqual([
+			"intel-opencl-icd",
+			"libigc2",
+			"libigdfcl2",
+		]);
+		expect(probe.warnings[0]).toContain("Intel Compute Runtime packages");
+	});
+
+	it("does not report OpenVINO devices when the runtime is not installed", () => {
+		const probe = detectOpenVinoDevices({
+			platform: "linux",
+			env: {},
+			...detector({
+				"/dev/accel": ["accel0"],
+				"/dev/dri": ["renderD128"],
+				"/usr/lib/x86_64-linux-gnu/intel-opencl/libigdrcl.so": true,
+			}),
+		});
+
+		expect(probe.runtimeAvailable).toBe(false);
+		expect(probe.devices).toEqual([]);
+		expect(probe.recommendedAsrDevice).toBeNull();
+		expect(probe.warnings).toContain(
+			"Intel accelerator nodes are present, but OpenVINO Runtime was not found; source setupvars.sh or set OpenVINO_DIR.",
+		);
+	});
+
+	it("treats sandbox-denied optional system paths as unavailable", () => {
+		const existsSync = (path: string): boolean => {
+			throw Object.assign(
+				new Error(`mobile-fs-shim: path escapes workspace root: ${path}`),
+				{ code: "EACCES" },
+			);
+		};
+		const readdirSync = (path: string): string[] => {
+			throw new Error(`unexpected readdir for ${path}`);
+		};
+
+		const probe = detectOpenVinoDevices({
+			platform: "linux",
+			env: {},
+			existsSync,
+			readdirSync,
+		});
+
+		expect(probe.runtimeAvailable).toBe(false);
+		expect(probe.devices).toEqual([]);
+		expect(probe.gpu.renderNodes).toEqual([]);
+		expect(probe.npu.accelNodes).toEqual([]);
+		expect(probe.recommendedAsrDevice).toBeNull();
+	});
+});
+
+describe("detectCpuFeatures", () => {
+	it("maps Linux ARM cpuinfo feature tokens to the shared probe shape", () => {
+		const cpuinfo = [
+			"processor\t: 0",
+			"Features\t: fp asimd evtstrm aes asimddp i8mm sve sve2",
+			"",
+		].join("\n");
+
+		expect(
+			detectCpuFeatures({
+				platform: "linux",
+				arch: "arm64",
+				readFileSync: () => cpuinfo,
+			}),
+		).toEqual({
+			neon: true,
+			dotprod: true,
+			i8mm: true,
+			sve: true,
+			sve2: true,
+		});
+	});
+
+	it("maps Android ARM cpuinfo aliases without assuming missing features", () => {
+		const cpuinfo = "Features\t: fp neon dotprod\n";
+
+		expect(
+			detectCpuFeatures({
+				platform: "android",
+				arch: "arm64",
+				readFileSync: () => cpuinfo,
+			}),
+		).toEqual({
+			neon: true,
+			dotprod: true,
+			i8mm: false,
+			sve: false,
+			sve2: false,
+		});
+	});
+
+	it("uses Darwin sysctl keys where available and treats missing keys as false", () => {
+		const values: Record<string, string> = {
+			"hw.optional.arm.FEAT_DotProd": "1\n",
+			"hw.optional.arm.FEAT_I8MM": "0\n",
+		};
+
+		expect(
+			detectCpuFeatures({
+				platform: "darwin",
+				arch: "arm64",
+				execFileSync: (_file, args) => {
+					const key = args[1];
+					if (key in values) return values[key];
+					throw new Error(`unknown sysctl ${key}`);
+				},
+			}),
+		).toEqual({
+			neon: true,
+			dotprod: true,
+			i8mm: false,
+			sve: false,
+			sve2: false,
+		});
+	});
+
+	it("does not claim CPU backend support for ARM when NEON evidence is absent", () => {
+		expect(
+			deviceCapsFromProbe({
+				totalRamGb: 16,
+				freeRamGb: 12,
+				gpu: null,
+				cpuCores: 8,
+				platform: "linux",
+				arch: "arm64",
+				appleSilicon: false,
+				recommendedBucket: "mid",
+				source: "os-fallback",
+			}),
+		).toEqual({
+			availableBackends: [],
+			ramMb: 16 * 1024,
+			cpuFeatures: undefined,
+		});
+	});
+});