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

package/src/services/memory-benchmark.test.ts

@@ -0,0 +1,91 @@
+import { MODEL_CATALOG } from "@elizaos/shared/local-inference";
+import { describe, expect, it } from "vitest";
+import {
+	buildMemoryBenchmarkPlan,
+	buildMemoryBenchmarkReport,
+	summarizeMemoryBenchmark,
+} from "./memory-benchmark";
+import type { HardwareProbe, InstalledModel } from "./types";
+
+function hardware(freeRamGb: number): HardwareProbe {
+	return {
+		totalRamGb: 16,
+		freeRamGb,
+		gpu: null,
+		cpuCores: 8,
+		platform: "darwin",
+		arch: "arm64",
+		appleSilicon: true,
+		recommendedBucket: "mid",
+		source: "os-fallback",
+	};
+}
+
+describe("memory benchmark report", () => {
+	it("marks the device-fit Eliza-1 tier and records curated resident estimates", () => {
+		const plan = buildMemoryBenchmarkPlan({
+			catalog: MODEL_CATALOG,
+			installed: [
+				{
+					id: "eliza-1-2b",
+					displayName: "Eliza-1 2B",
+					path: "/tmp/eliza-1-2b.bundle/text/eliza-1-2b-128k.gguf",
+					sizeBytes: 1_500_000_000,
+					bundleRoot: "/tmp/eliza-1-2b.bundle",
+					bundleSizeBytes: 2_000_000_000,
+					source: "eliza-download",
+					installedAt: "2026-06-22T00:00:00.000Z",
+					lastUsedAt: null,
+				} satisfies InstalledModel,
+			],
+			hardware: hardware(4.5),
+		});
+
+		const twoB = plan.find((model) => model.modelId === "eliza-1-2b");
+		expect(twoB?.installed).toBe(true);
+		expect(twoB?.selectedByDeviceFit).toBe(true);
+		// Gemma 4 cutover: KV is stock q8_0 (Gemma's MQA + windowed-SWA +
+		// shared-KV is already minimal; the head_dim=128 QJL kernel is retired).
+		expect(twoB?.plannedKvQuant).toBe("q8_0");
+		expect(twoB?.estimatedResidentMb).toBeGreaterThan(0);
+
+		const larger = plan.find((model) => model.modelId === "eliza-1-9b");
+		expect(larger?.fit).toBe("tight");
+		expect(larger?.selectedByDeviceFit).toBe(false);
+
+		const largest = plan.find((model) => model.modelId === "eliza-1-27b-256k");
+		expect(largest?.fit).toBe("wontfit");
+	});
+
+	it("summarizes load and telemetry counts", async () => {
+		const report = await buildMemoryBenchmarkReport(
+			{
+				catalog: MODEL_CATALOG,
+				installed: [],
+				hardware: hardware(2),
+			},
+			[
+				{
+					type: "model_load",
+					capability: "text",
+					modelKey: "m",
+					loadMs: 3,
+					atMs: 1,
+				},
+				{
+					type: "eviction",
+					capability: "text",
+					modelKey: "m",
+					reason: "fit",
+					estimatedMb: 512,
+					atMs: 2,
+				},
+			],
+		);
+
+		expect(report.deviceFit.modelId).toBeNull();
+		expect(report.telemetry.modelLoads).toBe(1);
+		expect(report.telemetry.evictions).toBe(1);
+		expect(summarizeMemoryBenchmark(report)).toContain("cloud fallback");
+	});
+});

package/src/services/memory-benchmark.ts

@@ -0,0 +1,354 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { performance } from "node:perf_hooks";
+import {
+	ELIZA_1_CONTEXT_TARGET,
+	ELIZA_1_KV_QUANT,
+	selectBestEliza1Fit,
+} from "@elizaos/shared/local-inference";
+import type { ArbiterEvent } from "./memory-arbiter";
+import type {
+	CatalogModel,
+	HardwareProbe,
+	InstalledModel,
+	ModelHubSnapshot,
+} from "./types";
+
+const BYTES_PER_MIB = 1024 * 1024;
+
+export interface MemoryBenchmarkModelPlan {
+	modelId: string;
+	displayName: string;
+	installed: boolean;
+	path: string | null;
+	bundleRoot: string | null;
+	bundleSizeMb: number | null;
+	fileSizeMb: number | null;
+	estimatedResidentMb: number;
+	catalogMinRamMb: number | null;
+	catalogContextLength: number | null;
+	fit: "fits" | "tight" | "wontfit";
+	selectedByDeviceFit: boolean;
+	plannedContextLength: number | null;
+	plannedKvQuant: typeof ELIZA_1_KV_QUANT | null;
+}
+
+export interface MemoryBenchmarkLoadResult {
+	modelId: string;
+	ok: boolean;
+	loadMs: number | null;
+	generateMs: number | null;
+	generatedTokens: number | null;
+	generatedTokensPerSec: number | null;
+	rssBeforeMb: number;
+	rssAfterLoadMb: number | null;
+	rssAfterGenerateMb: number | null;
+	rssDeltaMb: number | null;
+	loadedContextSize: number | null;
+	loadedCacheTypeK: string | null;
+	loadedCacheTypeV: string | null;
+	error: string | null;
+}
+
+export interface MemoryBenchmarkReport {
+	generatedAt: string;
+	host: {
+		platform: NodeJS.Platform;
+		arch: NodeJS.Architecture;
+		totalRamGb: number;
+		freeRamGb: number;
+		cpuCores: number;
+	};
+	deviceFit: {
+		modelId: string | null;
+		contextLength: number | null;
+		kvQuant: typeof ELIZA_1_KV_QUANT | null;
+		contextDownscaled: boolean;
+		reason: string | null;
+	};
+	models: MemoryBenchmarkModelPlan[];
+	loads: MemoryBenchmarkLoadResult[];
+	telemetry: {
+		modelLoads: number;
+		modelUnloads: number;
+		evictions: number;
+		memoryPressureEvents: number;
+		events: ArbiterEvent[];
+	};
+}
+
+export interface MemoryBenchmarkOptions {
+	loadInstalled?: boolean;
+	prompt?: string;
+	maxTokens?: number;
+	outFile?: string;
+}
+
+function mbFromBytes(bytes: number | undefined): number | null {
+	if (!Number.isFinite(bytes) || !bytes || bytes <= 0) return null;
+	return Math.ceil(bytes / BYTES_PER_MIB);
+}
+
+function catalogMinRamMb(model: CatalogModel): number | null {
+	return typeof model.minRamGb === "number"
+		? Math.ceil(model.minRamGb * 1024)
+		: null;
+}
+
+function estimateResidentMb(
+	model: CatalogModel,
+	installed: InstalledModel | undefined,
+): number {
+	const bundleMb = mbFromBytes(installed?.bundleSizeBytes);
+	if (bundleMb !== null) return bundleMb;
+	const minRamMb = catalogMinRamMb(model);
+	if (minRamMb !== null) return minRamMb;
+	const fileMb = mbFromBytes(installed?.sizeBytes);
+	if (fileMb !== null) return fileMb;
+	return Math.ceil((model.sizeGb ?? 0) * 1024);
+}
+
+function inferFit(
+	hardware: HardwareProbe,
+	model: CatalogModel,
+): "fits" | "tight" | "wontfit" {
+	if (typeof model.minRamGb !== "number") return "wontfit";
+	if (hardware.freeRamGb >= model.minRamGb) return "fits";
+	if (hardware.totalRamGb >= model.minRamGb) return "tight";
+	return "wontfit";
+}
+
+export function buildMemoryBenchmarkPlan(snapshot: {
+	catalog: CatalogModel[];
+	installed: InstalledModel[];
+	hardware: HardwareProbe;
+}): MemoryBenchmarkModelPlan[] {
+	const recommended = selectBestEliza1Fit(snapshot.hardware.freeRamGb);
+	const installedById = new Map(
+		snapshot.installed.map((model) => [model.id, model]),
+	);
+
+	return snapshot.catalog
+		.filter((model) => !model.hiddenFromCatalog)
+		.map((model) => {
+			const installed = installedById.get(model.id);
+			const selected = recommended?.tierId === model.id;
+			return {
+				modelId: model.id,
+				displayName: model.displayName,
+				installed: Boolean(installed),
+				path: installed?.path ?? null,
+				bundleRoot: installed?.bundleRoot ?? null,
+				bundleSizeMb: mbFromBytes(installed?.bundleSizeBytes),
+				fileSizeMb: mbFromBytes(installed?.sizeBytes),
+				estimatedResidentMb: estimateResidentMb(model, installed),
+				catalogMinRamMb: catalogMinRamMb(model),
+				catalogContextLength: model.contextLength ?? null,
+				fit: inferFit(snapshot.hardware, model),
+				selectedByDeviceFit: selected,
+				plannedContextLength: selected
+					? recommended.contextLength
+					: (model.contextLength ?? ELIZA_1_CONTEXT_TARGET),
+				plannedKvQuant: selected ? recommended.kvQuant : ELIZA_1_KV_QUANT,
+			};
+		});
+}
+
+function rssMb(): number {
+	return Math.round(process.memoryUsage.rss() / BYTES_PER_MIB);
+}
+
+function generatedTokenEstimate(text: string): number {
+	const trimmed = text.trim();
+	if (!trimmed) return 0;
+	return Math.max(1, Math.ceil(trimmed.length / 4));
+}
+
+function eventCounts(
+	events: ArbiterEvent[],
+): MemoryBenchmarkReport["telemetry"] {
+	return {
+		modelLoads: events.filter((event) => event.type === "model_load").length,
+		modelUnloads: events.filter((event) => event.type === "model_unload")
+			.length,
+		evictions: events.filter((event) => event.type === "eviction").length,
+		memoryPressureEvents: events.filter(
+			(event) => event.type === "memory_pressure",
+		).length,
+		events,
+	};
+}
+
+async function loadAndMeasure(
+	model: InstalledModel,
+	options: Required<Pick<MemoryBenchmarkOptions, "prompt" | "maxTokens">>,
+	deps: {
+		service: typeof import("./service").localInferenceService;
+		engine: typeof import("./engine").localInferenceEngine;
+	},
+): Promise<MemoryBenchmarkLoadResult> {
+	const before = rssMb();
+	const start = performance.now();
+	try {
+		const state = await deps.service.setActive(null, model.id);
+		const afterLoad = rssMb();
+		const loadMs = performance.now() - start;
+		let generateMs: number | null = null;
+		let generatedTokens: number | null = null;
+		let generatedTokensPerSec: number | null = null;
+		let afterGenerate: number | null = null;
+
+		if (deps.engine.hasLoadedModel()) {
+			const generateStart = performance.now();
+			const text = await deps.engine.generate({
+				prompt: options.prompt,
+				maxTokens: options.maxTokens,
+				temperature: 0,
+			});
+			generateMs = performance.now() - generateStart;
+			generatedTokens = generatedTokenEstimate(text);
+			generatedTokensPerSec =
+				generateMs > 0 ? generatedTokens / (generateMs / 1000) : null;
+			afterGenerate = rssMb();
+		}
+
+		return {
+			modelId: model.id,
+			ok: state.status === "ready",
+			loadMs: Math.round(loadMs),
+			generateMs: generateMs === null ? null : Math.round(generateMs),
+			generatedTokens,
+			generatedTokensPerSec:
+				generatedTokensPerSec === null
+					? null
+					: Number(generatedTokensPerSec.toFixed(2)),
+			rssBeforeMb: before,
+			rssAfterLoadMb: afterLoad,
+			rssAfterGenerateMb: afterGenerate,
+			rssDeltaMb: (afterGenerate ?? afterLoad) - before,
+			loadedContextSize: state.loadedContextSize ?? null,
+			loadedCacheTypeK: state.loadedCacheTypeK ?? null,
+			loadedCacheTypeV: state.loadedCacheTypeV ?? null,
+			error: state.status === "error" ? (state.error ?? "load failed") : null,
+		};
+	} catch (err) {
+		return {
+			modelId: model.id,
+			ok: false,
+			loadMs: null,
+			generateMs: null,
+			generatedTokens: null,
+			generatedTokensPerSec: null,
+			rssBeforeMb: before,
+			rssAfterLoadMb: null,
+			rssAfterGenerateMb: null,
+			rssDeltaMb: null,
+			loadedContextSize: null,
+			loadedCacheTypeK: null,
+			loadedCacheTypeV: null,
+			error: err instanceof Error ? err.message : String(err),
+		};
+	}
+}
+
+function hostFromHardware(
+	hardware: HardwareProbe,
+): MemoryBenchmarkReport["host"] {
+	return {
+		platform: hardware.platform,
+		arch: hardware.arch,
+		totalRamGb: hardware.totalRamGb,
+		freeRamGb: hardware.freeRamGb,
+		cpuCores: hardware.cpuCores,
+	};
+}
+
+function deviceFitFromHardware(
+	hardware: HardwareProbe,
+): MemoryBenchmarkReport["deviceFit"] {
+	const fit = selectBestEliza1Fit(hardware.freeRamGb);
+	return {
+		modelId: fit?.tierId ?? null,
+		contextLength: fit?.contextLength ?? null,
+		kvQuant: fit?.kvQuant ?? null,
+		contextDownscaled: fit?.contextDownscaled ?? false,
+		reason: fit?.reason ?? null,
+	};
+}
+
+export async function buildMemoryBenchmarkReport(
+	snapshot: Pick<ModelHubSnapshot, "catalog" | "installed" | "hardware">,
+	events: ArbiterEvent[] = [],
+	loads: MemoryBenchmarkLoadResult[] = [],
+): Promise<MemoryBenchmarkReport> {
+	return {
+		generatedAt: new Date().toISOString(),
+		host: hostFromHardware(snapshot.hardware),
+		deviceFit: deviceFitFromHardware(snapshot.hardware),
+		models: buildMemoryBenchmarkPlan(snapshot),
+		loads,
+		telemetry: eventCounts(events),
+	};
+}
+
+export async function runMemoryBenchmark(
+	options: MemoryBenchmarkOptions = {},
+): Promise<MemoryBenchmarkReport> {
+	const [{ localInferenceService }, { localInferenceEngine }] =
+		await Promise.all([import("./service"), import("./engine")]);
+	const events: ArbiterEvent[] = [];
+	const arbiter = localInferenceService.getMemoryArbiter();
+	const unsubscribe = arbiter.onEvent((event) => {
+		events.push(event);
+	});
+
+	const snapshot = await localInferenceService.snapshot();
+	const loads: MemoryBenchmarkLoadResult[] = [];
+	const prompt =
+		options.prompt ??
+		"Summarize why a curated Eliza-1 local model should choose its own memory profile.";
+	const maxTokens = options.maxTokens ?? 32;
+
+	try {
+		if (options.loadInstalled) {
+			for (const installed of snapshot.installed.filter(
+				(model) => model.source === "eliza-download",
+			)) {
+				loads.push(
+					await loadAndMeasure(
+						installed,
+						{ prompt, maxTokens },
+						{ service: localInferenceService, engine: localInferenceEngine },
+					),
+				);
+				await localInferenceService.clearActive(null);
+			}
+		}
+	} finally {
+		unsubscribe();
+	}
+
+	const report = await buildMemoryBenchmarkReport(snapshot, events, loads);
+	if (options.outFile) {
+		await mkdir(dirname(options.outFile), { recursive: true });
+		await writeFile(options.outFile, `${JSON.stringify(report, null, 2)}\n`);
+	}
+	return report;
+}
+
+export function summarizeMemoryBenchmark(
+	report: MemoryBenchmarkReport,
+): string {
+	const selected = report.deviceFit.modelId
+		? `${report.deviceFit.modelId} @ ${report.deviceFit.contextLength} ctx`
+		: "cloud fallback";
+	const installed = report.models.filter((model) => model.installed).length;
+	const loaded = report.loads.filter((load) => load.ok).length;
+	return [
+		`Eliza-1 memory benchmark (${report.generatedAt})`,
+		`Host: ${report.host.platform}/${report.host.arch}, ${report.host.freeRamGb.toFixed(1)} GB free of ${report.host.totalRamGb.toFixed(1)} GB`,
+		`Device-fit pick: ${selected}`,
+		`Catalog tiers: ${report.models.length}; installed: ${installed}; loaded: ${loaded}`,
+		`Telemetry: loads=${report.telemetry.modelLoads}, unloads=${report.telemetry.modelUnloads}, evictions=${report.telemetry.evictions}, pressure=${report.telemetry.memoryPressureEvents}`,
+	].join("\n");
+}

package/src/services/memory-monitor.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from "vitest";
+import { MemoryMonitor } from "./memory-monitor";
+import {
+	createEvictableModelRole,
+	type ResidentModelRole,
+	SharedResourceRegistry,
+} from "./voice/shared-resources";
+
+const MB = 1024 * 1024;
+
+/** A controllable evictable role for the eviction-order tests. */
+function fakeRole(
+	role: ResidentModelRole,
+	estimatedMb: number,
+): {
+	resource: ReturnType<typeof createEvictableModelRole>;
+	evictCount: () => number;
+	reload: () => void;
+} {
+	let resident = true;
+	let evictions = 0;
+	const resource = createEvictableModelRole({
+		id: `fake:${role}`,
+		role,
+		estimatedMb,
+		isResident: () => resident,
+		evict: async () => {
+			resident = false;
+			evictions += 1;
+		},
+	});
+	return {
+		resource,
+		evictCount: () => evictions,
+		reload: () => {
+			resident = true;
+		},
+	};
+}
+
+function monitorWithFreeMb(
+	registry: SharedResourceRegistry,
+	freeMb: number,
+	totalMb = 16 * 1024,
+): MemoryMonitor {
+	return new MemoryMonitor({
+		registry,
+		config: { lowWaterMb: 768, lowWaterFraction: 0.08, evictionCooldownMs: 0 },
+		sources: {
+			osMemory: () => ({ freeBytes: freeMb * MB, totalBytes: totalMb * MB }),
+			serverRssMb: async () => null,
+		},
+	});
+}
+
+describe("MemoryMonitor", () => {
+	it("does nothing while free RAM is above the low-water line", async () => {
+		const registry = new SharedResourceRegistry();
+		const text = fakeRole("text-target", 2000);
+		registry.acquire(text.resource);
+		const monitor = monitorWithFreeMb(registry, 8 * 1024); // plenty free
+		const action = await monitor.tick();
+		expect(action.evicted).toBeNull();
+		expect(action.exhausted).toBe(false);
+		expect(text.evictCount()).toBe(0);
+	});
+
+	it("defers eviction to the registry's external owner — no double-eviction (#8809 AC#2)", async () => {
+		const registry = new SharedResourceRegistry();
+		const tts = fakeRole("tts", 300);
+		const text = fakeRole("text-target", 2000);
+		registry.acquire(tts.resource);
+		registry.acquire(text.resource);
+
+		// The arbiter owns the eviction decision for this registry.
+		registry.claimEvictionOwnership("memory-arbiter");
+		const monitor = monitorWithFreeMb(registry, 256); // well under low-water
+		const deferred = await monitor.tick();
+		expect(deferred.delegated).toBe(true);
+		expect(deferred.evicted).toBeNull();
+		expect(tts.evictCount()).toBe(0); // the monitor did NOT evict
+		expect(text.evictCount()).toBe(0);
+
+		// Once the owner releases, the monitor resumes evicting itself.
+		registry.releaseEvictionOwnership("memory-arbiter");
+		const evicted = await monitor.tick();
+		expect(evicted.delegated).toBeFalsy();
+		expect(evicted.evicted?.role).toBe("tts");
+		expect(tts.evictCount()).toBe(1);
+	});
+
+	it("under pressure, evicts the lowest-priority resident role first", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		const tts = fakeRole("tts", 300);
+		const text = fakeRole("text-target", 4000);
+		// Register out of priority order on purpose.
+		registry.acquire(text.resource);
+		registry.acquire(tts.resource);
+		registry.acquire(emotion.resource);
+		const monitor = monitorWithFreeMb(registry, 200); // hard pressure
+
+		const first = await monitor.tick();
+		expect(first.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(1);
+		expect(tts.evictCount()).toBe(0);
+		expect(text.evictCount()).toBe(0);
+
+		// Still under pressure → next-lowest (tts) goes.
+		const second = await monitor.tick();
+		expect(second.evicted?.role).toBe("tts");
+		expect(tts.evictCount()).toBe(1);
+		expect(text.evictCount()).toBe(0);
+
+		// Then the text target — the last thing to go.
+		const third = await monitor.tick();
+		expect(third.evicted?.role).toBe("text-target");
+		expect(text.evictCount()).toBe(1);
+
+		// Nothing left.
+		const fourth = await monitor.tick();
+		expect(fourth.evicted).toBeNull();
+		expect(fourth.exhausted).toBe(true);
+	});
+
+	it("re-loaded roles become evictable again on the next pressure tick", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		registry.acquire(emotion.resource);
+		const monitor = monitorWithFreeMb(registry, 100);
+
+		const first = await monitor.tick();
+		expect(first.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(1);
+
+		// Nothing else resident → exhausted now.
+		const exhausted = await monitor.tick();
+		expect(exhausted.evicted).toBeNull();
+
+		// Caller re-loads the drafter on demand; pressure persists → it can be evicted again.
+		emotion.reload();
+		const second = await monitor.tick();
+		expect(second.evicted?.role).toBe("emotion");
+		expect(emotion.evictCount()).toBe(2);
+	});
+
+	it("honours the eviction cooldown between ticks", async () => {
+		const registry = new SharedResourceRegistry();
+		registry.acquire(fakeRole("emotion", 100).resource);
+		registry.acquire(fakeRole("tts", 100).resource);
+		const monitor = new MemoryMonitor({
+			registry,
+			config: {
+				lowWaterMb: 768,
+				lowWaterFraction: 0,
+				evictionCooldownMs: 10_000,
+			},
+			sources: {
+				osMemory: () => ({ freeBytes: 100 * MB, totalBytes: 16 * 1024 * MB }),
+				serverRssMb: async () => null,
+			},
+		});
+		const t0 = 1_000_000;
+		const a = await monitor.tick(t0);
+		expect(a.evicted?.role).toBe("emotion");
+		// Within the cooldown — no further eviction even though still under pressure.
+		const b = await monitor.tick(t0 + 5_000);
+		expect(b.evicted).toBeNull();
+		// After the cooldown — the next role goes.
+		const c = await monitor.tick(t0 + 11_000);
+		expect(c.evicted?.role).toBe("tts");
+	});
+
+	it("treats a huge llama-server RSS as pressure even when OS free looks fine", async () => {
+		const registry = new SharedResourceRegistry();
+		const emotion = fakeRole("emotion", 800);
+		registry.acquire(emotion.resource);
+		const monitor = new MemoryMonitor({
+			registry,
+			config: {
+				lowWaterMb: 1024,
+				lowWaterFraction: 0.05,
+				evictionCooldownMs: 0,
+			},
+			sources: {
+				// OS reports 4 GB free (looks fine), but the server is 15 GB on a 16 GB box.
+				osMemory: () => ({
+					freeBytes: 4 * 1024 * MB,
+					totalBytes: 16 * 1024 * MB,
+				}),
+				serverRssMb: async () => 15 * 1024,
+			},
+		});
+		const sample = await monitor.sample();
+		expect(monitor.isUnderPressure(sample)).toBe(true);
+		const action = await monitor.tick();
+		expect(action.evicted?.role).toBe("emotion");
+	});
+
+	it("start()/stop() arm and disarm the polling timer", () => {
+		const registry = new SharedResourceRegistry();
+		const monitor = monitorWithFreeMb(registry, 8 * 1024);
+		expect(monitor.isRunning()).toBe(false);
+		monitor.start();
+		expect(monitor.isRunning()).toBe(true);
+		monitor.start(); // idempotent
+		expect(monitor.isRunning()).toBe(true);
+		monitor.stop();
+		expect(monitor.isRunning()).toBe(false);
+	});
+
+	it("defaults serverRssMb to the real in-process RSS on the FFI path", async () => {
+		// No `serverRssMb` source injected → the default probe reads
+		// `process.memoryUsage().rss`, the in-process FFI host's resident set.
+		const registry = new SharedResourceRegistry();
+		const monitor = new MemoryMonitor({
+			registry,
+			config: { lowWaterMb: 768, lowWaterFraction: 0.08 },
+			sources: {
+				osMemory: () => ({
+					freeBytes: 8 * 1024 * MB,
+					totalBytes: 16 * 1024 * MB,
+				}),
+			},
+		});
+		const sample = await monitor.sample();
+		expect(sample.serverRssMb).not.toBeNull();
+		expect(sample.serverRssMb as number).toBeGreaterThan(0);
+		// The in-process RSS is bounded by total RAM (sanity, not a fabricated value).
+		expect(sample.serverRssMb as number).toBeLessThan(sample.totalMb);
+	});
+});