@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/system-metrics/cpu-details-linux.ts

@@ -0,0 +1,252 @@
+/**
+ * Mission Center's CPU page, from `/sys/devices/system/cpu`, `/proc` and hwmon.
+ * Split in two: the static facts go in the hardware inventory (they cannot change
+ * while the kernel is up), the live ones ride the tick.
+ *
+ * Package power is RAPL's cumulative energy counter, so it needs two samples like
+ * any other rate — the caller keeps the previous one.
+ */
+import type { CpuInfo } from "../../types/system-hardware.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+
+export const SYS_CPU = "/sys/devices/system/cpu";
+const RAPL_DIR = "/sys/class/powercap";
+const HWMON_DIR = "/sys/class/hwmon";
+
+/** `/sys/class/hwmon/<h>/name` of the package sensor, in preference order. */
+const PACKAGE_SENSORS = ["coretemp", "k10temp", "zenpower"];
+
+// ---------------------------------------------------------------- static
+
+export function readCpuInfo(fs: LinuxFs = realLinuxFs): CpuInfo | undefined {
+  const cpuinfo = fs.read("/proc/cpuinfo");
+  if (!cpuinfo) return undefined;
+  const topology = parseCpuinfoTopology(cpuinfo);
+  const caches = readCacheSizes(fs);
+
+  return {
+    name: topology.model,
+    sockets: topology.sockets,
+    physicalCores: topology.physicalCores,
+    logicalCores: topology.logicalCores,
+    ...defined("baseMHz", khzToMhz(readNumber(fs, `${SYS_CPU}/cpu0/cpufreq/base_frequency`))),
+    ...defined("maxMHz", khzToMhz(readNumber(fs, `${SYS_CPU}/cpu0/cpufreq/cpuinfo_max_freq`))),
+    ...defined("virtualization", virtualizationName(topology.flags)),
+    isVirtualMachine: topology.flags.has("hypervisor"),
+    ...defined("l1CacheBytes", caches.l1),
+    ...defined("l2CacheBytes", caches.l2),
+    ...defined("l3CacheBytes", caches.l3),
+    ...defined("freqDriver", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/scaling_driver`)),
+    ...defined("freqGovernor", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/scaling_governor`)),
+    ...defined("powerPreference", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/energy_performance_preference`)),
+  };
+}
+
+export interface CpuTopology {
+  model: string;
+  logicalCores: number;
+  physicalCores: number;
+  sockets: number;
+  flags: Set<string>;
+}
+
+/** `/proc/cpuinfo` is one block per logical CPU. Sockets are the distinct
+ *  `physical id`s; physical cores are `cpu cores` summed once per socket, which
+ *  is right for a hybrid part too — the kernel reports the real count there. */
+export function parseCpuinfoTopology(text: string): CpuTopology {
+  let model = "";
+  const flags = new Set<string>();
+  const coresPerSocket = new Map<string, number>();
+  let logicalCores = 0;
+  let currentSocket = "0";
+
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep < 0) continue;
+    const key = line.slice(0, sep).trim();
+    const value = line.slice(sep + 1).trim();
+    if (key === "processor") { logicalCores++; currentSocket = "0"; }
+    else if (key === "model name" && !model) model = value;
+    else if (key === "physical id") currentSocket = value;
+    else if (key === "cpu cores") coresPerSocket.set(currentSocket, Number(value) || 0);
+    else if (key === "flags" && flags.size === 0) for (const f of value.split(/\s+/)) flags.add(f);
+  }
+
+  const sockets = Math.max(coresPerSocket.size, 1);
+  let physicalCores = 0;
+  for (const n of coresPerSocket.values()) physicalCores += n;
+  return { model, logicalCores, physicalCores: physicalCores || logicalCores, sockets, flags };
+}
+
+/** Intel publishes `vmx`, AMD `svm`. Mission Center prints the marketing name. */
+export function virtualizationName(flags: ReadonlySet<string>): string | undefined {
+  if (flags.has("vmx")) return "Intel VT-x";
+  if (flags.has("svm")) return "AMD-V";
+  return undefined;
+}
+
+/** Cache sizes summed over DISTINCT caches: every CPU sharing one reports the
+ *  same `shared_cpu_list`, so that string is the deduplication key. L1 combines
+ *  data and instruction, which is what Mission Center shows as one figure. */
+export function readCacheSizes(fs: Pick<LinuxFs, "list" | "read">): { l1?: number; l2?: number; l3?: number } {
+  const seen = new Set<string>();
+  const totals = new Map<number, number>();
+
+  for (const cpu of fs.list(SYS_CPU) ?? []) {
+    if (!/^cpu\d+$/.test(cpu)) continue;
+    const cacheDir = `${SYS_CPU}/${cpu}/cache`;
+    for (const index of fs.list(cacheDir) ?? []) {
+      if (!index.startsWith("index")) continue;
+      const dir = `${cacheDir}/${index}`;
+      const level = readNumber(fs, `${dir}/level`);
+      const size = parseCacheSize(readAttr(fs, `${dir}/size`));
+      const shared = readAttr(fs, `${dir}/shared_cpu_list`);
+      if (level === undefined || size === undefined) continue;
+      const key = `${level}:${readAttr(fs, `${dir}/type`) ?? ""}:${shared ?? `${cpu}/${index}`}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      totals.set(level, (totals.get(level) ?? 0) + size);
+    }
+  }
+  return {
+    ...defined("l1", totals.get(1)),
+    ...defined("l2", totals.get(2)),
+    ...defined("l3", totals.get(3)),
+  };
+}
+
+/** sysfs writes cache sizes as "48K" / "30720K" / "16M". */
+export function parseCacheSize(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const m = /^(\d+)([KMG])?$/i.exec(raw.trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? "").toUpperCase();
+  const scale = unit === "G" ? 1024 ** 3 : unit === "M" ? 1024 ** 2 : unit === "K" ? 1024 : 1;
+  return n * scale;
+}
+
+// ---------------------------------------------------------------- live
+
+export interface RaplSample {
+  microjoules: number;
+  atSec: number;
+}
+
+export interface CpuLiveExtras {
+  currentMHz?: number;
+  tempC?: number;
+  powerW?: number;
+  threadCount?: number;
+  handleCount?: number;
+  uptimeSec?: number;
+}
+
+export interface CpuLiveResult {
+  extras: CpuLiveExtras;
+  /** RAPL baseline to hand back on the next tick; null when the host has none. */
+  rapl: RaplSample | null;
+}
+
+export function collectCpuLive(
+  prevRapl: RaplSample | null,
+  fs: Pick<LinuxFs, "list" | "read"> = realLinuxFs,
+  now: () => number = Date.now,
+): CpuLiveResult {
+  const atSec = now() / 1000;
+  const rapl = readRaplEnergy(fs, atSec);
+  const loadavg = fs.read("/proc/loadavg") ?? "";
+
+  return {
+    rapl,
+    extras: {
+      ...defined("currentMHz", meanCurrentMHz(fs)),
+      ...defined("tempC", readPackageTempC(fs)),
+      ...defined("powerW", raplWatts(prevRapl, rapl)),
+      ...defined("threadCount", parseThreadCount(loadavg)),
+      ...defined("handleCount", parseHandleCount(fs.read("/proc/sys/fs/file-nr"))),
+      ...defined("uptimeSec", parseUptimeSec(fs.read("/proc/uptime"))),
+    },
+  };
+}
+
+/** Mean of every online core's current clock. `scaling_cur_freq` is what the
+ *  governor asked for; `cpuinfo_cur_freq` needs root on some drivers, so it is
+ *  never read here. */
+export function meanCurrentMHz(fs: Pick<LinuxFs, "list" | "read">): number | undefined {
+  let sum = 0;
+  let count = 0;
+  for (const cpu of fs.list(SYS_CPU) ?? []) {
+    if (!/^cpu\d+$/.test(cpu)) continue;
+    const khz = readNumber(fs, `${SYS_CPU}/${cpu}/cpufreq/scaling_cur_freq`);
+    if (khz === undefined) continue;
+    sum += khz;
+    count++;
+  }
+  return count > 0 ? Math.round(sum / count / 1000) : undefined;
+}
+
+/** The package sensor, in preference order; `temp1_input` is the package on
+ *  coretemp ("Package id 0") and the die on k10temp. */
+export function readPackageTempC(fs: Pick<LinuxFs, "list" | "read">): number | undefined {
+  const chips = fs.list(HWMON_DIR) ?? [];
+  for (const wanted of PACKAGE_SENSORS) {
+    for (const chip of chips) {
+      if (readAttr(fs, `${HWMON_DIR}/${chip}/name`) !== wanted) continue;
+      const milli = readNumber(fs, `${HWMON_DIR}/${chip}/temp1_input`);
+      if (milli !== undefined) return Math.round(milli / 100) / 10;
+    }
+  }
+  return undefined;
+}
+
+/** Sum of every RAPL package domain. Intel exposes `intel-rapl:N`, AMD the same
+ *  interface; a host with neither (a VM, an ARM board) reports no power at all. */
+export function readRaplEnergy(fs: Pick<LinuxFs, "list" | "read">, atSec: number): RaplSample | null {
+  let microjoules = 0;
+  let found = false;
+  for (const entry of fs.list(RAPL_DIR) ?? []) {
+    if (!/^intel-rapl:\d+$/.test(entry)) continue;
+    const name = readAttr(fs, `${RAPL_DIR}/${entry}/name`) ?? "";
+    if (!name.startsWith("package")) continue;
+    const uj = readNumber(fs, `${RAPL_DIR}/${entry}/energy_uj`);
+    if (uj === undefined) continue;
+    microjoules += uj;
+    found = true;
+  }
+  return found ? { microjoules, atSec } : null;
+}
+
+/** Watts over the interval. The counter wraps at `max_energy_range_uj`, which a
+ *  negative delta reveals — one unmeasured tick is better than a false spike. */
+export function raplWatts(prev: RaplSample | null, next: RaplSample | null): number | undefined {
+  if (!prev || !next) return undefined;
+  const dt = next.atSec - prev.atSec;
+  const dj = next.microjoules - prev.microjoules;
+  if (!(dt > 0) || dj < 0) return undefined;
+  return Math.round(dj / dt / 1000) / 1000;
+}
+
+/** `/proc/loadavg`'s fourth field is `running/total` kernel tasks. */
+export function parseThreadCount(loadavg: string): number | undefined {
+  const m = /\s(\d+)\/(\d+)\s/.exec(` ${loadavg.trim()} `);
+  const n = m ? Number(m[2]) : NaN;
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** `/proc/sys/fs/file-nr`: allocated, free, max. The first is the live count. */
+export function parseHandleCount(fileNr: string | null): number | undefined {
+  const n = Number(fileNr?.trim().split(/\s+/)[0]);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+export function parseUptimeSec(uptime: string | null): number | undefined {
+  const n = Number(uptime?.trim().split(/\s+/)[0]);
+  return Number.isFinite(n) ? Math.round(n) : undefined;
+}
+
+const khzToMhz = (khz: number | undefined) => (khz === undefined ? undefined : Math.round(khz / 1000));
+
+function defined<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
+}

package/src/services/system-metrics/cpu-memory-collector.ts

@@ -1,9 +1,15 @@
 /**
- * Whole-machine CPU + memory from `node:os`. Runs in both tiers, spawns nothing.
+ * Whole-machine CPU + memory. Runs in both tiers.
+ *
+ * Reads files on Linux and spawns nothing there. On darwin it spawns exactly one
+ * `sysctl` per tick for swap, which `node:os` does not carry — measured at
+ * 1.33 ms, see `memory-darwin.ts`.
  */
 import os from "node:os";
 import { readFileSync } from "node:fs";
 import type { CpuMetrics, MemoryMetrics } from "../../types/system-metrics.ts";
+import { enrichMemory, readZramTotals, type ZramTotals } from "./memory-linux.ts";
+import { parseSwapUsage, readSwapUsage } from "./memory-darwin.ts";
 
 export interface CoreTimes {
   user: number;
@@ -11,8 +17,16 @@ export interface CoreTimes {
   sys: number;
   idle: number;
   irq: number;
+  /** Blocked on I/O: neither busy nor idle. `os.cpus()` has no field for it and
+   *  libuv reads the column into a throwaway, so these three are 0 on any host
+   *  whose sample came from there — see `sampleCpuTimes`. */
+  iowait: number;
+  softirq: number;
+  steal: number;
 }
 
+const NO_EXTRA = { iowait: 0, softirq: 0, steal: 0 } as const;
+
 export interface CpuTimesSample {
   times: CoreTimes[];
   /** Wall clock of the sample, epoch ms. */
@@ -20,38 +34,110 @@ export interface CpuTimesSample {
   model: string;
 }
 
+/** Read `/proc/stat` on Linux, null elsewhere or on failure. Injectable for tests. */
+export function readProcStat(): string | null {
+  if (process.platform !== "linux") return null;
+  try {
+    return readFileSync("/proc/stat", "utf-8");
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Read `os.cpus()` and copy the numbers out immediately. Bun 1.3.10 on Windows
- * returns the SAME `times` on a later call while the array from the previous
- * call is still referenced — the delta then reads 0 % forever, with no error
- * anywhere. Keeping only plain copies between ticks avoids it.
+ * Per-core times from a `/proc/stat` dump, in the file's own jiffies. Null when
+ * no `cpuN` line is present, so the caller can fall back.
+ *
+ * `guest`/`guest_nice` are deliberately NOT read: the kernel already counts them
+ * inside `user`/`nice`, so adding them would inflate the total and under-report
+ * every busy percentage on a host running VMs.
  */
-export function sampleCpuTimes(now: number = Date.now()): CpuTimesSample {
+export function parseProcStatCores(stat: string): CoreTimes[] | null {
+  const cores: CoreTimes[] = [];
+  for (const line of stat.split("\n")) {
+    const m = /^cpu(\d+)\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const n = m[2]!.trim().split(/\s+/).map(Number);
+    if (n.length < 8 || n.some((v) => !Number.isFinite(v))) return null;
+    cores[Number(m[1])] = {
+      user: n[0]!, nice: n[1]!, sys: n[2]!, idle: n[3]!,
+      iowait: n[4]!, irq: n[5]!, softirq: n[6]!, steal: n[7]!,
+    };
+  }
+  // A hole would mean a core index we never saw, which no kernel produces — but
+  // a sparse array here would crash the delta, so treat it as unusable.
+  if (cores.length === 0 || cores.some((c) => c === undefined)) return null;
+  return cores;
+}
+
+/**
+ * Prefer `/proc/stat`; fall back to `os.cpus()`.
+ *
+ * `os.cpus()` cannot express a core that is blocked on I/O. libuv's Linux
+ * `uv_cpu_info` reads the `iowait`, `softirq` and `steal` columns into a
+ * throwaway variable, so a core parked in iowait shows a *tiny* total delta with
+ * no idle in it — measured on this host, 6 jiffies of which 0 were idle while
+ * the kernel reported 195 of 201 in iowait, i.e. the Overview card drew one core
+ * pinned at a red **100%** while it was 3% busy and waiting on a disk write.
+ *
+ * The fallback still copies the numbers out immediately: Bun 1.3.10 on Windows
+ * returns the SAME `times` object on a later call while the previous array is
+ * still referenced, and the delta then reads 0 % forever with no error anywhere.
+ */
+export function sampleCpuTimes(
+  now: number = Date.now(),
+  stat: () => string | null = readProcStat,
+): CpuTimesSample {
   const cpus = os.cpus();
-  const times = cpus.map((c) => ({ ...c.times }));
-  return { times, at: now, model: cpus[0]?.model?.trim() ?? "" };
+  const model = cpus[0]?.model?.trim() ?? "";
+  const dump = stat();
+  const fromProc = dump ? parseProcStatCores(dump) : null;
+  if (fromProc && fromProc.length === cpus.length) return { times: fromProc, at: now, model };
+  return { times: cpus.map((c) => ({ ...c.times, ...NO_EXTRA })), at: now, model };
 }
 
 const round1 = (n: number): number => Math.round(n * 10) / 10;
 
-/** Busy % total + per core between two samples. Pure. First sample → all zeros. */
+/**
+ * Busy % total + per core between two samples. Pure. First sample → all zeros.
+ *
+ * The kernel share is `sys + irq` over the same interval — Mission Center draws
+ * it as a second, darker line under the total, so it is a SUBSET of `total` and
+ * must never be added to it.
+ */
 export function computeCpuFromSamples(prev: CpuTimesSample | null, next: CpuTimesSample): CpuMetrics {
-  const zeros: CpuMetrics = { total: 0, cores: next.times.map(() => 0), model: next.model };
+  const zeros: CpuMetrics = {
+    total: 0, cores: next.times.map(() => 0), model: next.model,
+    kernelPercent: 0, coreKernel: next.times.map(() => 0),
+  };
   if (!prev || prev.times.length !== next.times.length) return zeros;
 
   let busySum = 0;
+  let kernelSum = 0;
   let totalSum = 0;
+  const coreKernel: number[] = [];
   const cores = next.times.map((n, i) => {
     const p = prev.times[i]!;
-    const idle = n.idle - p.idle;
-    const total = (n.user - p.user) + (n.nice - p.nice) + (n.sys - p.sys) + idle + (n.irq - p.irq);
-    if (!(total > 0)) return 0;
-    busySum += total - idle;
+    // Waiting on I/O is not work. Folding it into `idle` is what `top` and
+    // Mission Center both do, and leaving it out of `total` altogether is the
+    // bug that drew an idle core at 100% — see `sampleCpuTimes`.
+    const notBusy = (n.idle - p.idle) + (n.iowait - p.iowait);
+    const kernel = (n.sys - p.sys) + (n.irq - p.irq) + (n.softirq - p.softirq);
+    const total = (n.user - p.user) + (n.nice - p.nice) + kernel
+      + notBusy + (n.steal - p.steal);
+    if (!(total > 0)) {
+      coreKernel.push(0);
+      return 0;
+    }
+    busySum += total - notBusy;
+    kernelSum += kernel;
     totalSum += total;
-    return clampPercent((total - idle) / total * 100);
+    coreKernel.push(clampPercent(kernel / total * 100));
+    return clampPercent((total - notBusy) / total * 100);
   });
   const total = totalSum > 0 ? clampPercent(busySum / totalSum * 100) : 0;
-  return { total, cores, model: next.model };
+  const kernelPercent = totalSum > 0 ? clampPercent(kernelSum / totalSum * 100) : 0;
+  return { total, cores, model: next.model, kernelPercent, coreKernel };
 }
 
 function clampPercent(v: number): number {
@@ -59,6 +145,20 @@ function clampPercent(v: number): number {
   return round1(Math.min(100, Math.max(0, v)));
 }
 
+/**
+ * Seconds since boot, on all three platforms — `os.uptime()` reads
+ * `/proc/uptime`, `kern.boottime` and `GetTickCount64` respectively.
+ *
+ * Linux has a finer figure of its own and `collectDevices` merges it OVER this
+ * one; the reason this exists is that the per-device collector is null off
+ * Linux, so "Up time" was an em dash — the claim that the host could not be
+ * asked how long it had been up — on macOS and Windows both.
+ */
+export function hostUptimeSec(): number | undefined {
+  const seconds = os.uptime();
+  return Number.isFinite(seconds) && seconds > 0 ? Math.round(seconds) : undefined;
+}
+
 /** Read `/proc/meminfo` on Linux, null elsewhere or on failure. Injectable for tests. */
 export function readMeminfo(): string | null {
   if (process.platform !== "linux") return null;
@@ -82,8 +182,19 @@ export function parseMemAvailableBytes(meminfo: string): number | null {
  * and `os.freemem()` is within 0.2 GiB of CIM's `FreePhysicalMemory`. On Linux
  * `freemem()` is `MemFree`, which makes a warm page cache look like a nearly
  * full machine — `MemAvailable` is what `free` and Task-Manager-like tools show.
+ * On **darwin** `freemem()` is already right and must be left alone: it agrees
+ * with what `top` calls unused (75 MB against this figure's 124 MB on the same
+ * host, sampled seconds apart), which is the number Activity Monitor shows.
+ *
+ * Swap is the one field macOS publishes and `os` does not, so it is fetched
+ * separately — see `memory-darwin.ts` for why that costs a spawn and why the
+ * page counts from `vm_stat` are deliberately not used.
  */
-export function collectMemory(meminfo: () => string | null = readMeminfo): MemoryMetrics {
+export function collectMemory(
+  meminfo: () => string | null = readMeminfo,
+  zram: () => ZramTotals | undefined = defaultZram,
+  swapusage: () => string | null = readSwapUsage,
+): MemoryMetrics {
   const totalBytes = os.totalmem();
   let availableBytes = os.freemem();
   const info = meminfo();
@@ -97,5 +208,16 @@ export function collectMemory(meminfo: () => string | null = readMeminfo): Memor
   const availableMB = round1(availableBytes / MB);
   const usedMB = round1(Math.max(totalMB - availableMB, 0));
   const percent = totalMB > 0 ? round1(usedMB / totalMB * 100) : 0;
-  return { totalMB, usedMB, availableMB, percent };
+  const base: MemoryMetrics = { totalMB, usedMB, availableMB, percent };
+  // `info` is null off Linux, so the composition fields simply stay absent there
+  // — but swap is not one of those: macOS answers for it, and leaving it absent
+  // rendered an em dash on a host with 8 GB of swap in use.
+  if (info) return enrichMemory(base, info, zram());
+  return { ...base, ...parseSwapUsage(swapusage()) };
+}
+
+/** Two `/sys` reads on a host that has zram and one cheap directory listing on
+ *  one that does not — small enough to run per tick, unlike the DIMM layout. */
+function defaultZram(): ZramTotals | undefined {
+  return readZramTotals();
 }

package/src/services/system-metrics/device-collector-linux.ts

@@ -0,0 +1,31 @@
+/** Every per-device Linux collector as one tick-shaped call. */
+import { collectLinuxDiskDevices } from "./disk-devices-linux.ts";
+import { collectLinuxNicDevices } from "./net-devices-linux.ts";
+import { collectLinuxFans } from "./fans-linux.ts";
+import { collectCpuLive } from "./cpu-details-linux.ts";
+import { collectLinuxGpus } from "./gpu-devices-linux.ts";
+import type { DrmGpuCollector } from "./gpu-fdinfo-linux.ts";
+import { realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+import type { DeviceCollection, DeviceSampleState } from "./device-collector-types.ts";
+
+export function collectLinuxDevices(
+  prev: DeviceSampleState,
+  drm: DrmGpuCollector,
+  fs: LinuxFs = realLinuxFs,
+  now: () => number = Date.now,
+): DeviceCollection {
+  const disks = collectLinuxDiskDevices(prev.disks, fs, now);
+  const nics = collectLinuxNicDevices(prev.nics, fs, now);
+  const cpu = collectCpuLive(prev.rapl, fs, now);
+  // The same walk the process rows are built from: asking here first (or second)
+  // costs nothing, because the collector memoises one result per tick.
+  const gpus = collectLinuxGpus(prev.gpus, drm.usage(), fs, now);
+  return {
+    disks: disks.disks,
+    nics: nics.nics,
+    fans: collectLinuxFans(fs),
+    cpu: cpu.extras,
+    gpus: gpus.gpus,
+    next: { disks: disks.next, nics: nics.next, rapl: cpu.rapl, gpus: gpus.next },
+  };
+}

package/src/services/system-metrics/device-collector-types.ts

@@ -0,0 +1,40 @@
+/** Shape of the per-device (drive / interface) half of a tick, platform-neutral so
+ *  the tick assembler does not import a Linux module to name its own state. */
+import type { CpuMetrics, DiskMetrics, FanMetrics, GpuMetrics, NicMetrics } from "../../types/system-metrics.ts";
+import type { DiskSampleState } from "./disk-devices-linux.ts";
+import type { NicSampleState } from "./net-devices-linux.ts";
+import type { RaplSample } from "./cpu-details-linux.ts";
+import type { GpuSampleState } from "./gpu-devices-linux.ts";
+
+/** Previous counters, per device id. Each device is measured against its own
+ *  baseline, so one appearing mid-session costs one unavailable tick and never a
+ *  spike measured from zero. */
+export interface DeviceSampleState {
+  disks: DiskSampleState;
+  nics: NicSampleState;
+  /** Cumulative RAPL energy, the baseline package power is measured against. */
+  rapl: RaplSample | null;
+  /** Per-card rc6 / uncore counters. */
+  gpus: GpuSampleState;
+}
+
+export const EMPTY_DEVICE_STATE: DeviceSampleState = {
+  disks: new Map(), nics: new Map(), rapl: null, gpus: new Map(),
+};
+
+export interface DeviceCollection {
+  disks: DiskMetrics[];
+  nics: NicMetrics[];
+  /** Empty where the host has no fan tachometer. */
+  fans: FanMetrics[];
+  /** Merged over the cross-platform `CpuMetrics` by the tick, never replacing it. */
+  cpu: Partial<CpuMetrics>;
+  /** Cards this platform reads from sysfs. Appended to whatever the vendor-tool
+   *  collector (nvidia-smi) found, which covers the drivers sysfs cannot. */
+  gpus: GpuMetrics[];
+  next: DeviceSampleState;
+}
+
+/** Synchronous by design: every source is a small sysfs read, so there is no
+ *  subprocess to await and no reason for the tick to yield. */
+export type DeviceCollector = (prev: DeviceSampleState) => DeviceCollection;