Measure GPU and CPU energy from hardware counters and sum them; drop the modelled fallback

distinct_agent/energy.py

@@ -1,46 +1,59 @@
-"""Honest energy accounting for local inference windows.
+"""Measured energy for a local inference window.
 
-Every backend reports its measurement scope.  RAPL is CPU-package energy, not
-whole-computer electricity.
+Everything here is a hardware counter. There is no model, no estimate and no
+default: a component either has a counter this can read, in which case its
+joules are real, or it does not, in which case it is named as absent and the
+run reports no figure rather than a plausible one.
 
-The backend ladder runs measured-first, modelled-last, and the two never mix:
+WHAT IS MEASURED
 
-1. hardware counters report **measured** joules on a hardware scope: Zeus
-   where it is installed and finds a device (the only backend here that can
-   see a GPU), the Energy Meter Interface or the Energy Meter performance
-   counter on Windows, and pyRAPL or direct ``/sys/class/powercap`` RAPL on
-   Linux;
-2. when no counter exists, :class:`CpuLoadModelMeter` reports **modelled**
-   joules from observed busy-CPU seconds and a stated per-core power figure,
-   on its own ``system-cpu-modelled`` scope.
+A run's energy is the sum of the components that did the run, each read from
+its own counter over the same window:
 
-WSL2, and why an agent should not run there
--------------------------------------------
+* **NVIDIA GPU**, through NVML (``nvidia-ml-py``). Where the driver exposes
+  ``nvmlDeviceGetTotalEnergyConsumption`` (Volta and later) that counter is an
+  integrating energy register in millijoules, so the interval energy is an
+  exact difference with no sampling error. Older boards fall back to
+  integrating ``nvmlDeviceGetPowerUsage`` on a 50 ms timer, and say so in the
+  scope. Every board on the machine is summed.
+* **CPU package**, through RAPL: ``/sys/class/powercap`` directly on Linux
+  (with pyRAPL as a secondary reader), and on Windows the Energy Meter
+  Interface driver, or the Energy Meter performance counter where EMI is
+  absent.
+* **Apple silicon**, through ``powermetrics``, which needs root and says so
+  when it does not have it.
 
-This came up as a plausible simplification: run the agent under WSL2, get the
-Linux RAPL reader and the executed bubblewrap sandbox, and drop the Windows
-code entirely. **It does not work, and it would replace a working measurement
-with an absence.** Two independent reasons, either sufficient:
+For inference on a GPU the board is nearly all of the energy, which is why the
+GPU is read first and why reading only the CPU package -- as this module used
+to -- understates a GPU run by roughly an order of magnitude.
+
+WHAT IS NOT MEASURED, AND IS NEVER GUESSED
+
+Power-supply conversion loss, fans, storage, the mainboard and anything else
+between the wall and these components. No multiplier is applied to reach for a
+whole-machine figure, because that would convert a measurement into a model
+while leaving the word "measured" on it. The reported number is therefore a
+floor for the machine's true draw, and the scope string names exactly which
+components it covers.
+
+Where a component is expected but silent, its absence is attached to the
+figure, so a total missing its GPU can be told apart from a total that never
+had one.
+
+WSL2, AND WHY AN AGENT SHOULD NOT RUN THERE
+
+Running the agent under WSL2 to get the Linux RAPL reader and the bubblewrap
+sandbox does not work, for two independent reasons:
 
 * The Microsoft WSL2 kernel is built with ``CONFIG_POWERCAP`` unset on the
-  current rolling branch, so ``/sys/class/powercap`` does not exist to read.
-* Even with a rebuilt kernel, Hyper-V does not pass the RAPL energy MSRs
-  through to the utility VM. ``intel_rapl_msr`` matches the CPU (the host's
-  CPUID is visible), attempts ``MSR_RAPL_POWER_UNIT``, fails, and registers no
-  zones. The perf path is gated by the same read. Being root inside WSL2 buys
-  nothing, which is the reverse of bare-metal Linux.
-
-NVML GPU power does work under WSL2, so a GPU worker there would measure its
-GPU and nothing else. For a CPU worker the answer is simply that the energy
-figure disappears, which on a project whose claim is measurement is the worst
-available trade. The Windows path stays.
-
-A modelled figure is a real number about a real run, and it is labelled as a
-model everywhere it appears.  Because it carries its own scope, the session
-roll-up in the UI will never sum it with a measured figure: different scopes
-are different measurement boundaries and stay in separate lines.  What this
-module still never does is report a modelled value *as* a measurement, or
-report zero for a window it knows nothing about.
+  current rolling branch, so ``/sys/class/powercap`` does not exist.
+* Even with a rebuilt kernel, Hyper-V does not pass the RAPL energy MSRs to the
+  utility VM. ``intel_rapl_msr`` matches the CPU, attempts
+  ``MSR_RAPL_POWER_UNIT``, fails, and registers no zones. Being root inside
+  WSL2 buys nothing, which is the reverse of bare-metal Linux.
+
+NVML does work under WSL2, so a GPU worker there measures its GPU and nothing
+else. For a CPU worker the figure disappears entirely. The Windows path stays.
 """
 
 from __future__ import annotations
@@ -68,6 +81,9 @@ class EnergyToken:
     available: bool
     reason: str | None = None
     counter_value: float | None = None
+    #: When the counter was actually sampled, which is not when start() was
+    #: called. See CumulativeEnergyMeter.stop for why the difference matters.
+    counter_at: float | None = None
     opaque: Any = field(default=None, repr=False, compare=False)
 
 
@@ -223,6 +239,11 @@ class CumulativeEnergyMeter:
                 False,
                 f"counter read failed: {type(exc).__name__}",
             )
+        # Taken AFTER the read, and paired with it. Some readers are slow --
+        # the Windows performance-counter path shells out to typeperf, whose
+        # first sample costs the better part of a second -- and the interval
+        # the counter difference describes begins when the counter was
+        # sampled, not when this method was entered.
         return EnergyToken(
             self._meter_id,
             self.provider,
@@ -230,6 +251,7 @@ class CumulativeEnergyMeter:
             started,
             True,
             counter_value=value,
+            counter_at=self._monotonic(),
         )
 
     def stop(self, token: EnergyToken) -> EnergyUsage:
@@ -249,6 +271,21 @@ class CumulativeEnergyMeter:
                 None,
                 f"counter read failed: {type(exc).__name__}",
             )
+        # THE AVERAGE IS OVER THE COUNTER'S WINDOW, NOT THIS METHOD'S.
+        #
+        # `duration` above is wall time from start() being called to stop()
+        # returning, which is the right figure to report as how long the run
+        # took. It is the wrong denominator for average power, because it
+        # includes the cost of the two counter reads that bracket it. On the
+        # Windows performance-counter path each read shells out to typeperf,
+        # whose first sample takes the better part of a second: a five-second
+        # run was reported over a six-and-a-half-second window, so its average
+        # watts came out about a fifth low while its joules were exactly right.
+        #
+        # The energy is the counter difference, and the counter difference
+        # describes the interval between the two samples. Dividing by that
+        # interval is the only division that gives the power actually drawn.
+        sampled_at = self._monotonic()
         delta = end_value - token.counter_value
         if delta < 0:
             return EnergyUsage(
@@ -261,7 +298,10 @@ class CumulativeEnergyMeter:
                 "counter reset or wrapped during measurement",
             )
         joules = delta * self._scale
-        average = joules / duration if duration > 0 else None
+        counter_window = (
+            sampled_at - token.counter_at if token.counter_at is not None else duration
+        )
+        average = joules / counter_window if counter_window > 0 else None
         return EnergyUsage(
             self.provider,
             self.scope,
@@ -637,6 +677,81 @@ class _EmiReader:
         return float(self._measure_raw())
 
 
+class _PdhRaplReader:
+    """The same counter as typeperf, read through PDH with no sample wait.
+
+    WHY THIS EXISTS: typeperf COSTS MORE THAN THE RUN IT MEASURES.
+
+    ``typeperf <counter> -sc 1`` spawns a process and, because its formatted
+    output is defined in terms of a sampling interval, waits about a second
+    before printing anything. Two of those bracket every run, so a worker on
+    this path spent roughly 1.4 s of wall clock per request doing nothing but
+    reading a number, and short runs were mostly measurement.
+
+    ``\\Energy Meter(...)\\Energy`` is a cumulative raw counter, not a rate, so
+    it needs no interval at all: one ``PdhCollectQueryData`` and the raw value
+    is the total energy so far. The query is opened once and kept, so a read is
+    two library calls and no process.
+
+    Falls back to typeperf when PDH is not usable, because a slow reading is
+    better than none.
+    """
+
+    def __init__(self, counter_path: str) -> None:
+        self.counter_path = counter_path
+        self._pdh: Any = None
+        self._query: Any = None
+        self._counter: Any = None
+        self._open()
+
+    def _open(self) -> None:
+        import ctypes
+        from ctypes import wintypes
+
+        pdh = ctypes.WinDLL("pdh.dll")
+        query = wintypes.LPVOID()
+        status = pdh.PdhOpenQueryW(None, 0, ctypes.byref(query))
+        if status != 0:
+            raise OSError(status, "PdhOpenQuery failed")
+        counter = wintypes.LPVOID()
+        # The English variant so a localised Windows still resolves the path
+        # this project hard-codes.
+        status = pdh.PdhAddEnglishCounterW(
+            query, self.counter_path, 0, ctypes.byref(counter)
+        )
+        if status != 0:
+            pdh.PdhCloseQuery(query)
+            raise OSError(status, f"PdhAddEnglishCounter failed for {self.counter_path}")
+        self._pdh, self._query, self._counter = pdh, query, counter
+
+    def __call__(self) -> float:
+        import ctypes
+        from ctypes import wintypes
+
+        class _RawCounter(ctypes.Structure):
+            _fields_ = [
+                ("CStatus", wintypes.DWORD),
+                ("TimeStamp", wintypes.FILETIME),
+                ("FirstValue", ctypes.c_longlong),
+                ("SecondValue", ctypes.c_longlong),
+                ("MultiCount", wintypes.DWORD),
+            ]
+
+        status = self._pdh.PdhCollectQueryData(self._query)
+        if status != 0:
+            raise OSError(status, "PdhCollectQueryData failed")
+        counter_type = wintypes.DWORD()
+        raw = _RawCounter()
+        status = self._pdh.PdhGetRawCounterValue(
+            self._counter, ctypes.byref(counter_type), ctypes.byref(raw)
+        )
+        if status != 0:
+            raise OSError(status, "PdhGetRawCounterValue failed")
+        if raw.CStatus != 0:
+            raise OSError(raw.CStatus, "the energy counter reported an error status")
+        return float(raw.FirstValue)
+
+
 class WindowsPerformanceCounterRaplMeter(CumulativeEnergyMeter):
     """Optional Windows RAPL package meter via the Energy Meter counter set.
 
@@ -659,13 +774,20 @@ class WindowsPerformanceCounterRaplMeter(CumulativeEnergyMeter):
         available = platform.system() == "Windows" or reader is not None
         reason: str | None = None
         if reader is None:
-            executable = shutil.which("typeperf") if available else None
-            if executable is None:
-                available = False
-                reason = "Windows typeperf is unavailable"
-                reader = _missing_reader
-            else:
-                reader = _TypeperfRaplReader(executable, counter_path)
+            # PDH first: same counter, no sampling wait, no subprocess. See
+            # _PdhRaplReader for why that is worth the ctypes.
+            try:
+                reader = _PdhRaplReader(counter_path) if available else None
+            except Exception:  # noqa: BLE001 - fall back rather than fail
+                reader = None
+            if reader is None:
+                executable = shutil.which("typeperf") if available else None
+                if executable is None:
+                    available = False
+                    reason = "no Windows energy counter is readable by PDH or typeperf"
+                    reader = _missing_reader
+                else:
+                    reader = _TypeperfRaplReader(executable, counter_path)
         if available and probe:
             try:
                 _finite_counter(reader())
@@ -673,7 +795,11 @@ class WindowsPerformanceCounterRaplMeter(CumulativeEnergyMeter):
                 available = False
                 reason = f"Windows RAPL counter unavailable: {type(exc).__name__}"
         super().__init__(
-            provider="windows-performance-counter-rapl",
+            provider=(
+                "windows-energy-counter-pdh"
+                if isinstance(reader, _PdhRaplReader)
+                else "windows-energy-counter-typeperf"
+            ),
             scope="cpu-package",
             reader=reader,
             joules_per_counter_unit=self.PICOWATT_HOUR_TO_JOULES,
@@ -767,71 +893,238 @@ class PowercapRaplMeter(CumulativeEnergyMeter):
                 self._reason = f"RAPL counter probe failed: {type(exc).__name__}"
 
 
-#: The stated assumption behind the modelled backend, overridable by the
-#: operator who knows their hardware. 12.5 W per busy core is a mid-range
-#: figure for a loaded x86 server core including its share of uncore.
-MODEL_WATTS_PER_BUSY_CORE_ENV = "DISTINCT_MODEL_WATTS_PER_CORE"
-DEFAULT_MODEL_WATTS_PER_BUSY_CORE = 12.5
-
+# THE MODELLED METER IS GONE, AND THIS IS WHAT IT WAS.
+#
+# The modelled meter multiplied busy core-seconds from /proc/stat by a
+# hard-coded 12.5 watts per core and reported the product as the run's energy,
+# labelled "modelled". It was removed rather than improved, for two reasons
+# that are worth keeping so it is not reinvented:
+#
+#   * The constant was invented. Nothing measured it, nothing on the machine
+#     validated it, and no two machines would have shared it. A figure derived
+#     from it is not a property of the run it describes, which makes it the one
+#     thing this project cannot ship: a number about energy that nobody can
+#     reproduce, on a site whose whole claim is that its numbers are measured.
+#
+#   * It could not run where it was needed. It read /proc/stat, so on Windows,
+#     the platform it existed to be the fallback for, it failed at construction
+#     and the ladder fell straight through it. It had been the documented
+#     Windows fallback for months while being, on Windows, dead code.
+#
+# A run with no counter now reports an absence carrying the reason. The rest of
+# the product already treats an absence as a first-class state -- it is drawn
+# as a dash and the words "No data", never as zero -- so there was somewhere
+# honest for that answer to go.
+
+
+# ---------------------------------------------------------------------------
+# NVIDIA, THROUGH NVML RATHER THAN A SUBPROCESS
+#
+# For a worker that runs a model on a GPU, the GPU is the measurement. CPU
+# package counters see the tokeniser and the sampling loop and essentially none
+# of the matrix multiplication, so a ladder that reads RAPL and stops has
+# measured the wrong component and reported it as the run's energy.
+#
+# Two ways to ask NVML, and the difference matters:
+#
+#   * ``nvmlDeviceGetTotalEnergyConsumption`` is a monotonic ENERGY counter in
+#     millijoules, maintained by the driver since the last reset. Volta and
+#     later. Reading it before and after and subtracting gives the energy of
+#     the interval exactly, with no sampling error at all, and it cannot miss a
+#     spike that happened between two samples.
+#
+#   * ``nvmlDeviceGetPowerUsage`` is an instantaneous POWER reading in
+#     milliwatts. Turning that into energy means sampling it on a timer and
+#     integrating, which is an approximation whose error depends on how spiky
+#     the load is. LLM decode is spiky.
+#
+# So the counter is used wherever it exists and the sampler is the fallback for
+# Pascal and older, which is stated in the scope rather than hidden. The
+# fallback integrates with the trapezium rule on real elapsed timestamps, not
+# a nominal interval, because a sampling thread that is descheduled for 40ms
+# must not be assumed to have slept for exactly 10.
+# ---------------------------------------------------------------------------
+
+NVML_SAMPLE_INTERVAL_SECONDS = 0.05
+
+
+class _NvmlSampler:
+    """Integrates instantaneous board power on a background thread.
+
+    Only used where the energy counter is absent. Trapezium rule over real
+    timestamps: if the thread is late, the gap it actually slept is the gap it
+    integrates over.
+    """
 
-class CpuLoadModelMeter:
-    """Modelled energy from system-wide busy-CPU seconds, clearly labelled.
+    def __init__(
+        self,
+        read_watts: Callable[[], float],
+        *,
+        interval: float = NVML_SAMPLE_INTERVAL_SECONDS,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._read = read_watts
+        self._interval = interval
+        self._monotonic = monotonic
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._joules = 0.0
+        self._samples = 0
+        self._failed: str | None = None
 
-    Used only when no hardware counter is available, so a run still reports a
-    real figure about itself rather than nothing. The model is deliberately
-    simple and deliberately stated: busy core-seconds across the whole system
-    during the window, multiplied by a per-core power figure the operator can
-    override with ``DISTINCT_MODEL_WATTS_PER_CORE``.
+    def start(self) -> None:
+        self._thread = threading.Thread(target=self._run, name="distinct-nvml", daemon=True)
+        self._thread.start()
 
-    It reports on its own scope, ``system-cpu-modelled``, so the session
-    roll-up never sums it with a measured cpu-package figure. Whole-system
-    busy time is the honest choice over per-process time because inference
-    runs in a supervised child process; the cost is that other activity on
-    the machine during the window is included, and the scope name says so.
+    def _run(self) -> None:
+        try:
+            previous_watts = self._read()
+            previous_at = self._monotonic()
+            self._samples = 1
+        except Exception as exc:  # noqa: BLE001 - recorded, not raised on a thread
+            self._failed = f"{type(exc).__name__}: {exc}"
+            return
+        while not self._stop.wait(self._interval):
+            try:
+                watts = self._read()
+            except Exception as exc:  # noqa: BLE001
+                self._failed = f"{type(exc).__name__}: {exc}"
+                return
+            now = self._monotonic()
+            self._joules += (watts + previous_watts) / 2.0 * (now - previous_at)
+            previous_watts, previous_at = watts, now
+            self._samples += 1
+
+    def stop(self) -> tuple[float, int, str | None]:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+        return self._joules, self._samples, self._failed
+
+
+class NvmlGpuEnergyMeter:
+    """Measured GPU energy for every NVIDIA board on this machine.
+
+    Every board is summed, because a worker that spreads a model across two
+    cards has spent the energy of both and reporting one of them would be a
+    measurement of half the machine.
     """
 
-    provider = "cpu-load-model"
-    scope = "system-cpu-modelled"
+    provider = "nvidia-nvml"
 
     def __init__(
         self,
         *,
-        watts_per_busy_core: float | None = None,
+        nvml: Any = None,
         monotonic: Callable[[], float] = time.monotonic,
-        stat_path: str = "/proc/stat",
+        sample_interval: float = NVML_SAMPLE_INTERVAL_SECONDS,
     ) -> None:
-        import os
-
         self._monotonic = monotonic
+        self._interval = sample_interval
         self._meter_id = uuid.uuid4().hex
-        self._stat_path = stat_path
-        if watts_per_busy_core is None:
-            raw = os.environ.get(MODEL_WATTS_PER_BUSY_CORE_ENV, "")
+        self._nvml: Any = None
+        self._handles: list[Any] = []
+        self._counter = False
+        self._available = False
+        self._reason: str | None = None
+        self._names: tuple[str, ...] = ()
+
+        module = nvml
+        if module is None:
             try:
-                watts_per_busy_core = float(raw) if raw else DEFAULT_MODEL_WATTS_PER_BUSY_CORE
-            except ValueError:
-                watts_per_busy_core = DEFAULT_MODEL_WATTS_PER_BUSY_CORE
-        if not math.isfinite(watts_per_busy_core) or not 0.5 <= watts_per_busy_core <= 500:
-            watts_per_busy_core = DEFAULT_MODEL_WATTS_PER_BUSY_CORE
-        self.watts_per_busy_core = float(watts_per_busy_core)
-        self._clock_ticks = float(os.sysconf("SC_CLK_TCK")) if hasattr(os, "sysconf") else 100.0
+                import pynvml as module  # type: ignore[no-redef]
+            except ImportError:
+                self._reason = (
+                    "nvidia-ml-py is not installed, so NVIDIA GPU energy cannot be read"
+                )
+                return
+        try:
+            module.nvmlInit()
+        except Exception as exc:  # noqa: BLE001 - any NVML failure means no GPU here
+            self._reason = f"NVML would not start: {_nvml_reason(exc)}"
+            return
+        self._nvml = module
+        try:
+            count = int(module.nvmlDeviceGetCount())
+            names = []
+            for index in range(count):
+                handle = module.nvmlDeviceGetHandleByIndex(index)
+                self._handles.append(handle)
+                names.append(_nvml_text(module.nvmlDeviceGetName(handle)))
+            self._names = tuple(names)
+        except Exception as exc:  # noqa: BLE001
+            self._reason = f"NVML found no usable device: {_nvml_reason(exc)}"
+            self._shutdown()
+            return
+        if not self._handles:
+            self._reason = "NVML started but this machine has no NVIDIA GPU"
+            self._shutdown()
+            return
+        # The energy counter is per device and not universal. It is only used
+        # when EVERY board has it, because a total that mixed an exact counter
+        # on one card with an integrated estimate on another would carry the
+        # error of the estimate under the name of the counter.
+        self._counter = all(self._try_energy(handle) is not None for handle in self._handles)
+        if not self._counter and self._try_power(self._handles[0]) is None:
+            self._reason = "NVML reports neither an energy counter nor a power reading"
+            self._shutdown()
+            return
         self._available = True
-        self._reason: str | None = None
+
+    # -- NVML calls, each returning None rather than raising ----------------
+
+    def _try_energy(self, handle: Any) -> float | None:
         try:
-            _finite_counter(self._busy_seconds())
-        except Exception as exc:
-            self._available = False
-            self._reason = f"/proc/stat unavailable: {type(exc).__name__}"
-
-    def _busy_seconds(self) -> float:
-        with open(self._stat_path, "r", encoding="ascii") as handle:
-            first = handle.readline().split()
-        if not first or first[0] != "cpu":
-            raise ValueError("unexpected /proc/stat format")
-        values = [float(item) for item in first[1:11]]
-        # busy = everything except idle (4th) and iowait (5th).
-        busy_ticks = sum(values) - values[3] - (values[4] if len(values) > 4 else 0.0)
-        return busy_ticks / self._clock_ticks
+            return float(self._nvml.nvmlDeviceGetTotalEnergyConsumption(handle)) / 1000.0
+        except Exception:  # noqa: BLE001 - unsupported on pre-Volta
+            return None
+
+    def _try_power(self, handle: Any) -> float | None:
+        try:
+            return float(self._nvml.nvmlDeviceGetPowerUsage(handle)) / 1000.0
+        except Exception:  # noqa: BLE001
+            return None
+
+    def _shutdown(self) -> None:
+        if self._nvml is not None:
+            try:
+                self._nvml.nvmlShutdown()
+            except Exception:  # noqa: BLE001 - shutting down a dead handle is not news
+                pass
+            self._nvml = None
+
+    def _total_energy_joules(self) -> float:
+        total = 0.0
+        for handle in self._handles:
+            value = self._try_energy(handle)
+            if value is None:
+                raise RuntimeError("energy counter disappeared mid-run")
+            total += value
+        return total
+
+    def _total_watts(self) -> float:
+        total = 0.0
+        for handle in self._handles:
+            value = self._try_power(handle)
+            if value is None:
+                raise RuntimeError("power reading disappeared mid-run")
+            total += value
+        return total
+
+    # -- meter interface ----------------------------------------------------
+
+    @property
+    def scope(self) -> str:
+        """Names the boards and how they were read, because both change the number."""
+
+        how = "energy-counter" if self._counter else "power-sampled"
+        if not self._names:
+            return f"gpu-nvidia-{how}"
+        return f"gpu-nvidia-{how} ({len(self._names)} board{'s' if len(self._names) > 1 else ''})"
+
+    @property
+    def devices(self) -> tuple[str, ...]:
+        return self._names
 
     @property
     def available(self) -> bool:
@@ -847,53 +1140,92 @@ class CpuLoadModelMeter:
             return EnergyToken(
                 self._meter_id, self.provider, self.scope, started, False, self._reason
             )
-        try:
-            value = _finite_counter(self._busy_seconds())
-        except Exception as exc:
+        if self._counter:
+            try:
+                value = _finite_counter(self._total_energy_joules())
+            except Exception as exc:  # noqa: BLE001
+                return EnergyToken(
+                    self._meter_id,
+                    self.provider,
+                    self.scope,
+                    started,
+                    False,
+                    f"NVML energy counter read failed: {_nvml_reason(exc)}",
+                )
             return EnergyToken(
-                self._meter_id,
-                self.provider,
-                self.scope,
-                started,
-                False,
-                f"busy-time read failed: {type(exc).__name__}",
+                self._meter_id, self.provider, self.scope, started, True, counter_value=value
             )
+        sampler = _NvmlSampler(
+            self._total_watts, interval=self._interval, monotonic=self._monotonic
+        )
+        sampler.start()
         return EnergyToken(
-            self._meter_id, self.provider, self.scope, started, True, counter_value=value
+            self._meter_id, self.provider, self.scope, started, True, opaque=sampler
         )
 
     def stop(self, token: EnergyToken) -> EnergyUsage:
         _check_token_owner(token, self._meter_id)
         duration = max(0.0, self._monotonic() - token.started_monotonic)
-        if not token.available or token.counter_value is None:
+        if not token.available:
             return _unavailable_usage(token, duration)
-        try:
-            end_value = _finite_counter(self._busy_seconds())
-        except Exception as exc:
-            return EnergyUsage(
-                self.provider,
-                self.scope,
-                False,
-                duration,
-                None,
-                None,
-                f"busy-time read failed: {type(exc).__name__}",
-            )
-        busy_core_seconds = max(0.0, end_value - token.counter_value)
-        joules = busy_core_seconds * self.watts_per_busy_core
+        if self._counter:
+            if token.counter_value is None:
+                return _unavailable_usage(token, duration)
+            try:
+                end = _finite_counter(self._total_energy_joules())
+            except Exception as exc:  # noqa: BLE001
+                return EnergyUsage(
+                    self.provider,
+                    self.scope,
+                    False,
+                    duration,
+                    None,
+                    None,
+                    f"NVML energy counter read failed: {_nvml_reason(exc)}",
+                )
+            # The driver's counter resets when the driver reloads. A total that
+            # went backwards is that, not negative energy, and is refused.
+            if end < token.counter_value:
+                return EnergyUsage(
+                    self.provider,
+                    self.scope,
+                    False,
+                    duration,
+                    None,
+                    None,
+                    "the NVML energy counter was reset during this run",
+                )
+            joules = end - token.counter_value
+        else:
+            sampler = token.opaque
+            if not isinstance(sampler, _NvmlSampler):
+                return _unavailable_usage(token, duration)
+            joules, samples, failed = sampler.stop()
+            if failed is not None:
+                return EnergyUsage(
+                    self.provider, self.scope, False, duration, None, None,
+                    f"GPU power sampling failed: {failed}",
+                )
+            if samples < 2:
+                return EnergyUsage(
+                    self.provider, self.scope, False, duration, None, None,
+                    "the run was shorter than one GPU sampling interval",
+                )
         average = joules / duration if duration > 0 else None
-        return EnergyUsage(
-            self.provider,
-            self.scope,
-            True,
-            duration,
-            joules,
-            average,
-            # Available AND carrying a reason: the reason states the model so
-            # the assumption travels with every figure derived from it.
-            f"modelled: busy core-seconds x {self.watts_per_busy_core:g} W per core",
-        )
+        return EnergyUsage(self.provider, self.scope, True, duration, joules, average)
+
+
+def _nvml_text(value: Any) -> str:
+    """NVML returns bytes on some builds and str on others."""
 
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return str(value)
+
+
+def _nvml_reason(exc: BaseException) -> str:
+    text = str(exc).strip()
+    return text or type(exc).__name__
 
 class ZeusEnergyMeter:
     """Measured energy via Zeus (https://ml.energy/zeus/measure/).
@@ -1246,85 +1578,242 @@ class PowermetricsProbeMeter:
         return _unavailable_usage(token, max(0.0, time.monotonic() - token.started_at))
 
 
+
+# ---------------------------------------------------------------------------
+# WHY THE METER IS A SUM AND NOT A CHOICE
+#
+# This used to pick one backend off a ladder and report it as "the" energy of a
+# run. On a machine that runs the model on a GPU that is the wrong component:
+# the CPU package counter sees the tokeniser, the sampler and the scheduler,
+# and almost none of the arithmetic, so the ladder measured something real,
+# reported it accurately, and answered a question nobody asked.
+#
+# A run's energy is the energy of the parts of the machine that did it. Where
+# more than one of those parts has a counter, all of them are read and the
+# figures are added, and the scope says which parts were included.
+#
+# What is NOT done here, deliberately:
+#
+#   * No estimate is ever added to a measurement. Every component in the sum
+#     is a hardware counter. A component with no counter is named in
+#     `missing`, so the total is explicitly a lower bound rather than
+#     silently one.
+#   * Nothing is scaled up to guess at the whole wall socket. Power supply
+#     loss, fans, drives and the board itself are real energy this cannot see,
+#     and inventing a PUE-style multiplier would turn a measurement into a
+#     model while keeping the word "measured" on it.
+#
+# So the number is: the energy drawn by the components named in the scope,
+# measured by their own counters, during the run. That sentence is what the
+# figure means, and it is the sentence the site prints.
+# ---------------------------------------------------------------------------
+
+
+class CompositeEnergyMeter:
+    """Every counter this machine has, read together and summed."""
+
+    provider = "composite"
+
+    def __init__(
+        self,
+        meters: Sequence[EnergyMeter],
+        *,
+        missing: Sequence[str] = (),
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._meters = [meter for meter in meters if meter.available]
+        self._missing = tuple(missing)
+        self._monotonic = monotonic
+        self._meter_id = uuid.uuid4().hex
+        self._reason = None if self._meters else "no hardware energy counter is available"
+
+    @property
+    def meters(self) -> tuple[EnergyMeter, ...]:
+        return tuple(self._meters)
+
+    @property
+    def scope(self) -> str:
+        if not self._meters:
+            return "unknown"
+        return " + ".join(meter.scope for meter in self._meters)
+
+    @property
+    def available(self) -> bool:
+        return bool(self._meters)
+
+    @property
+    def unavailable_reason(self) -> str | None:
+        return self._reason
+
+    def start(self) -> EnergyToken:
+        started = self._monotonic()
+        if not self._meters:
+            return EnergyToken(
+                self._meter_id, self.provider, self.scope, started, False, self._reason
+            )
+        # Started in order and stopped in reverse, so the window each component
+        # measures encloses the window of the one started after it. No
+        # component can then report energy from a period another did not cover.
+        tokens = [meter.start() for meter in self._meters]
+        return EnergyToken(
+            self._meter_id, self.provider, self.scope, started, True, opaque=tokens
+        )
+
+    def stop(self, token: EnergyToken) -> EnergyUsage:
+        _check_token_owner(token, self._meter_id)
+        duration = max(0.0, self._monotonic() - token.started_monotonic)
+        tokens = token.opaque
+        if not token.available or not isinstance(tokens, list):
+            return _unavailable_usage(token, duration)
+
+        parts: list[EnergyUsage] = []
+        for meter, part_token in zip(reversed(self._meters), reversed(tokens), strict=True):
+            parts.append(meter.stop(part_token))
+        parts.reverse()
+
+        measured = [part for part in parts if part.available and part.joules is not None]
+        if not measured:
+            reasons = "; ".join(
+                f"{part.provider}: {part.reason}" for part in parts if part.reason
+            )
+            return EnergyUsage(
+                self.provider, self.scope, False, duration, None, None,
+                reasons or "no component returned a measurement",
+            )
+
+        joules = sum(float(part.joules) for part in measured)
+        average = joules / duration if duration > 0 else None
+        scope = " + ".join(part.scope for part in measured)
+        # A component that was expected and did not report is named, because a
+        # total missing its GPU is a different number from a total that never
+        # had one and the reader cannot tell them apart from the figure alone.
+        absent = [part.provider for part in parts if part not in measured]
+        absent.extend(self._missing)
+        reason = None
+        if absent:
+            reason = "not included: " + ", ".join(dict.fromkeys(absent))
+        return EnergyUsage(self.provider, scope, True, duration, joules, average, reason)
+
+
+def _cpu_meter(operating_system: str) -> EnergyMeter | None:
+    """This machine's CPU-package counter, or None if it has none we can read."""
+
+    if operating_system == "Linux":
+        # Direct powercap first: the same counter pyRAPL wraps, without
+        # importing an abandoned package that logs at import time.
+        for candidate in (PowercapRaplMeter(), PyRaplEnergyMeter()):
+            if candidate.available:
+                return candidate
+        return None
+    if operating_system == "Windows":
+        # EMI is the documented driver interface to the same RAPL counters;
+        # the performance-counter reader is the fallback where it is absent.
+        for candidate in (WindowsEmiMeter(), WindowsPerformanceCounterRaplMeter()):
+            if candidate.available:
+                return candidate
+        return None
+    if operating_system == "Darwin":
+        probe = PowermetricsProbeMeter()
+        return probe if probe.available else None
+    return None
+
+
+def _gpu_meter() -> EnergyMeter | None:
+    """This machine's GPU counter, preferring the library to the subprocess."""
+
+    nvml = NvmlGpuEnergyMeter()
+    if nvml.available:
+        return nvml
+    # nvidia-smi is the same driver reached the slow way. It stays as a
+    # fallback for a machine where the library is missing but the tool is on
+    # PATH, which is the ordinary state of a fresh CUDA install.
+    smi = NvidiaSmiPowerMeter()
+    if smi.available:
+        return smi
+    return None
+
+
 def detect_energy_meter(*, system: str | None = None) -> EnergyMeter:
-    """Choose a backend: measured counters first, the stated model last.
+    """Every counter this machine has, composed into one meter.
 
-    A run should virtually always come back with an energy figure; that is
-    the product. What varies, and is always labelled, is whether the figure
-    was measured off a hardware counter or modelled from CPU load.
+    THE OLD LADDER MEASURED THE WRONG COMPONENT AND SAID SO CONFIDENTLY.
 
-    Zeus is tried before everything else on the platforms it supports, because
-    it is the only backend here that can see a GPU, and a GPU is where the
-    energy is on any worker that has one. It is optional: when it is absent, or
-    finds no device, or lacks the privileges RAPL needs, the ladder below is
-    unchanged.
+    It returned the first backend that worked, in an order that put CPU package
+    counters above the GPU. On a worker running a 7B model on a graphics card
+    that is close to the worst possible choice: RAPL sees the tokeniser and the
+    sampling loop, the board does the arithmetic, and the run was reported as
+    the energy of the part that did least of the work.
+
+    Now every component with a counter is read and the figures are summed. A
+    machine with a GPU and readable CPU counters reports both; a headless CPU
+    box reports its package; a machine with neither reports an absence with the
+    reason, and never a number.
+
+    Zeus is tried first where it is installed because it wraps several vendors
+    behind one interface and its authors maintain the per-vendor detail. It is
+    optional, and its absence changes nothing: the backends below are this
+    project's own and do not depend on it.
     """
 
     operating_system = platform.system() if system is None else system
+
     if operating_system != "Windows":
         # Upstream does not support Windows, so it is not attempted there
-        # rather than being attempted and failing on every start-up.
+        # rather than failing on every start.
         zeus = ZeusEnergyMeter()
         if zeus.available:
             return zeus
-    if operating_system == "Darwin":
-        # Zeus above already covers a Mac with zeus-apple-silicon installed.
-        # Below it, powermetrics is the OS's own meter but needs root; the
-        # probe meter names that requirement, and the load model keeps a Mac
-        # worker reporting a labelled figure rather than nothing.
-        probe = PowermetricsProbeMeter()
-        if probe.available:
-            return probe
-        model = CpuLoadModelMeter()
-        if model.available:
-            return model
+
+    parts: list[EnergyMeter] = []
+    missing: list[str] = []
+
+    gpu = _gpu_meter()
+    if gpu is not None:
+        parts.append(gpu)
+
+    cpu = _cpu_meter(operating_system)
+    if cpu is not None:
+        parts.append(cpu)
+    else:
+        missing.append(f"cpu package ({operating_system} counter unavailable)")
+
+    if not parts:
+        # NO COUNTER MEANS NO FIGURE.
+        #
+        # There used to be a modelled meter here: busy core-seconds times a
+        # hard-coded 12.5 watts per core, labelled "modelled". Two things were
+        # wrong with it. The constant was invented, so the number it produced
+        # was not a property of the machine it claimed to describe; and it read
+        # /proc/stat, so on Windows -- the platform it was the fallback for --
+        # it could never initialise at all and the ladder fell through it to
+        # nothing. A figure nobody can reproduce is worse than an absence on a
+        # site whose entire claim is measurement, so the absence is what is
+        # reported, with the reason attached.
+        reasons = "; ".join(
+            reason
+            for reason in (
+                NvmlGpuEnergyMeter().unavailable_reason,
+                _cpu_unavailable_reason(operating_system),
+            )
+            if reason
+        )
         return UnavailableEnergyMeter(
-            probe.unavailable_reason or "no macOS energy backend is available"
+            reasons or f"no energy counter is readable on {operating_system}"
         )
+
+    if len(parts) == 1 and not missing:
+        return parts[0]
+    return CompositeEnergyMeter(parts, missing=missing)
+
+
+def _cpu_unavailable_reason(operating_system: str) -> str | None:
     if operating_system == "Linux":
-        # Direct powercap first: same hardware counter pyRAPL wraps, without
-        # importing an abandoned package that logs warnings at import time.
-        powercap = PowercapRaplMeter()
-        if powercap.available:
-            return powercap
-        pyrapl = PyRaplEnergyMeter()
-        if pyrapl.available:
-            return pyrapl
-        # A machine whose inference runs on the GPU: the board figure is the
-        # honest one when the CPU counters are fenced off (as they are in
-        # containers), and it is measured rather than modelled.
-        smi = NvidiaSmiPowerMeter()
-        if smi.available:
-            return smi
-        model = CpuLoadModelMeter()
-        if model.available:
-            return model
-        return UnavailableEnergyMeter(powercap.unavailable_reason or "Linux RAPL unavailable")
+        return PowercapRaplMeter().unavailable_reason
     if operating_system == "Windows":
-        # EMI first: the same RAPL counters, read through the documented driver
-        # interface rather than through a typeperf subprocess and a CSV parse.
-        emi = WindowsEmiMeter()
-        if emi.available:
-            return emi
-        counter = WindowsPerformanceCounterRaplMeter()
-        if counter.available:
-            return counter
-        smi = NvidiaSmiPowerMeter()
-        if smi.available:
-            return smi
-        # Modelled, and labelled as modelled. A Windows worker with no usable
-        # counter used to report nothing at all, which made every one of its
-        # runs an absence; the model is a real number about a real run and it
-        # carries its own scope so it can never be summed with a measurement.
-        model = CpuLoadModelMeter()
-        if model.available:
-            return model
-        return UnavailableEnergyMeter(
-            emi.unavailable_reason
-            or counter.unavailable_reason
-            or "no Windows energy counter is available"
-        )
-    return UnavailableEnergyMeter(f"no energy backend for {operating_system}")
+        return WindowsEmiMeter().unavailable_reason
+    if operating_system == "Darwin":
+        return PowermetricsProbeMeter().unavailable_reason
+    return f"no CPU energy counter is known for {operating_system}"
 
 
 def _check_token_owner(token: EnergyToken, meter_id: str) -> None:

distinct_server/comparators.py

@@ -0,0 +1,264 @@
+"""What a number of joules actually amounts to, in things people have done.
+
+WHY A SECOND TABLE, WHEN render.COMPARATORS ALREADY EXISTS
+
+That one answers "how long would this run an appliance": *twelve seconds of a
+10 W bulb*. It is exact and it is nearly useless at the small end, because
+nobody has an intuition for twelve seconds of a light. This table answers the
+other question: "how much of a whole, familiar thing is this": *a tenth of a
+cup of tea*. Those are the units people already own.
+
+HOW THE NUMBERS WERE GOT
+
+Every entry is either derived here from physics, or is a rated figure for a
+common appliance run for a stated time. The working is in the note beside it so
+a reader can check it rather than trust it, which is the same standard the rest
+of this project applies to the figures it republishes.
+
+Water is the recurring one, so it is worth stating once. Heating water takes
+``mass x 4186 J/kg/K x temperature rise``. A 250 ml mug from a 20 C tap to
+100 C is ``0.25 x 4186 x 80 = 83.7 kJ`` of heat into the water. A domestic
+kettle puts roughly 80% of what it draws into the water, the rest going into
+the element, the body and the steam, so the wall figure is about 105 kJ. Where
+an entry says "in a kettle" it is the wall figure, because that is the
+electricity somebody actually paid for.
+
+Anything expressed in kWh is converted at 3.6 MJ per kWh.
+
+WHAT IS DELIBERATELY NOT HERE
+
+No CO2, no water footprint, no land, no money. Those are conversions with
+assumptions of their own -- grid mix, time of day, jurisdiction -- and this
+project does not make assessor-created estimates. A joule compared to another
+joule needs no assumption at all, which is why every entry on this list is an
+energy and nothing else.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+KWH = 3_600_000.0
+#: Specific heat capacity of water, J/(kg K).
+WATER_SPECIFIC_HEAT = 4186.0
+#: A domestic kettle delivers roughly this share of its draw into the water.
+KETTLE_EFFICIENCY = 0.80
+#: Standard gravity, m/s^2.
+G = 9.81
+
+
+def _heat_water(litres: float, rise_c: float, *, efficiency: float = 1.0) -> float:
+    return litres * WATER_SPECIFIC_HEAT * rise_c / efficiency
+
+
+def _appliance(watts: float, seconds: float) -> float:
+    return watts * seconds
+
+
+def _lift(kilograms: float, metres: float) -> float:
+    return kilograms * G * metres
+
+
+@dataclass(frozen=True)
+class Comparator:
+    """One familiar thing, and what it costs."""
+
+    #: Reads after a number: "about 2.5 <label>".
+    label: str
+    #: Energy for exactly one of them, in joules.
+    joules: float
+    #: How that figure was arrived at.
+    note: str
+
+    #: Plural form where "s" will not do.
+    plural: str = ""
+
+    def name(self, count: float) -> str:
+        """Singular only when the number in front of it will print as "1".
+
+        Matched to :func:`_round_count` rather than to the raw float, because
+        "about 0.98 minute" is what a tolerance around 1.0 produces and it
+        reads as a mistake.
+        """
+
+        return self.label if _round_count(count) == "1" else (self.plural or self.label + "s")
+
+
+#: Ordered by size. Roughly one entry every quarter-decade, so a picker can
+#: nearly always find one that puts the figure between 0.1 and 100 of itself.
+COMPARATORS: tuple[Comparator, ...] = (
+    # ---- sub-joule to 100 J: the scale of a short CPU-only run -----------
+    Comparator("heartbeat", 1.0, "about 1 J of mechanical work per beat at rest"),
+    Comparator("apple lifted one metre", 0.98, "0.1 kg x 9.81 m/s^2 x 1 m", "apples lifted one metre"),
+    Comparator("second of a smoke alarm", 1.0, "1 W standby draw for 1 s", "seconds of a smoke alarm"),
+    Comparator("phone screen-second", 2.0, "about 2 W for the panel, for 1 s", "phone screen-seconds"),
+    Comparator("teaspoon of water warmed by 1 C", 20.9, "0.005 kg x 4186 x 1", "teaspoons of water warmed by 1 C"),
+    Comparator("second of an LED bulb", 10.0, "10 W for 1 s", "seconds of an LED bulb"),
+    Comparator("second of a wifi router", 6.0, "6 W for 1 s", "seconds of a wifi router"),
+    Comparator("AA battery's worth of torch light", 15_120.0, "2.8 Ah x 1.5 V alkaline = 4.2 Wh"),
+    Comparator("stair step climbed", 132.0, "75 kg x 9.81 x 0.18 m riser", "stair steps climbed"),
+    Comparator("second of a laptop", 50.0, "50 W for 1 s", "seconds of a laptop"),
+    Comparator("press-up", 200.0, "about 200 J of work for an adult", "press-ups"),
+    Comparator("second of a desktop PC", 150.0, "150 W for 1 s", "seconds of a desktop PC"),
+    Comparator("minute of an LED bulb", 600.0, "10 W for 60 s", "minutes of an LED bulb"),
+    Comparator("second of a gaming GPU at full load", 350.0, "350 W for 1 s", "seconds of a gaming GPU at full load"),
+    Comparator("smartphone photo taken", 500.0, "about 0.5 kJ including capture and write", "smartphone photos taken"),
+    # ---- 1 kJ to 100 kJ: a normal LLM run --------------------------------
+    Comparator("second of a kettle", 3000.0, "3 kW element for 1 s", "seconds of a kettle"),
+    Comparator("minute of a wifi router", 360.0, "6 W for 60 s", "minutes of a wifi router"),
+    Comparator("minute of a laptop", 3000.0, "50 W for 60 s", "minutes of a laptop"),
+    Comparator("Google search", 1080.0, "0.3 Wh, Google's own published figure", "Google searches"),
+    Comparator("minute of a desktop PC", 9000.0, "150 W for 60 s", "minutes of a desktop PC"),
+    Comparator("litre of water warmed by 1 C", 4186.0, "1 kg x 4186 x 1", "litres of water warmed by 1 C"),
+    Comparator("minute of a 55-inch TV", 6000.0, "100 W for 60 s", "minutes of a 55-inch TV"),
+    Comparator("phone charged by 1%", 623.0, "4500 mAh x 3.85 V = 17.3 Wh, one hundredth", "% of a phone charge"),
+    Comparator("minute of a gaming GPU at full load", 21_000.0, "350 W for 60 s", "minutes of a gaming GPU at full load"),
+    Comparator("slice of toast", 96_000.0, "800 W toaster for 2 minutes", "slices of toast"),
+    Comparator("mug of tea boiled", 104_650.0, "0.25 l from 20 C to 100 C in a kettle at 80%", "mugs of tea boiled"),
+    Comparator("minute in a microwave", 60_000.0, "1 kW draw for 60 s", "minutes in a microwave"),
+    Comparator("egg boiled", 130_000.0, "hob heating 0.4 l to 100 C and holding it", "eggs boiled"),
+    Comparator("hour of a wifi router", 21_600.0, "6 W for 1 h", "hours of a wifi router"),
+    Comparator("minute of an electric shower", 510_000.0, "8.5 kW for 60 s", "minutes of an electric shower"),
+    Comparator("hour of an LED bulb", 36_000.0, "10 W for 1 h", "hours of an LED bulb"),
+    Comparator("hour of a laptop", 180_000.0, "50 W for 1 h", "hours of a laptop"),
+    Comparator("phone charged from flat", 62_300.0, "4500 mAh x 3.85 V = 17.3 Wh", "phones charged from flat"),
+    Comparator("pint of water boiled", 237_800.0, "0.568 l from 20 C to 100 C in a kettle at 80%", "pints of water boiled"),
+    Comparator("hour of a 55-inch TV", 360_000.0, "100 W for 1 h", "hours of a 55-inch TV"),
+    Comparator("piece of bread baked", 250_000.0, "oven share for one loaf's worth of a slice", "pieces of bread baked"),
+    # ---- 1 MJ to 100 MJ: a long session, or a machine left running -------
+    Comparator("hour of a desktop PC", 540_000.0, "150 W for 1 h", "hours of a desktop PC"),
+    Comparator("hour of a gaming GPU at full load", 1_260_000.0, "350 W for 1 h", "hours of a gaming GPU at full load"),
+    Comparator("hour of a fridge", 144_000.0, "40 W average duty for 1 h", "hours of a fridge"),
+    Comparator("load of washing", 2_520_000.0, "0.7 kWh, a 40 C cotton cycle", "loads of washing"),
+    Comparator("dishwasher cycle", 3_600_000.0, "1.0 kWh eco programme", "dishwasher cycles"),
+    Comparator("shower taken", 4_080_000.0, "8.5 kW electric shower for 8 minutes", "showers taken"),
+    Comparator("hour of an oven", 7_200_000.0, "2 kW for 1 h", "hours of an oven"),
+    Comparator("tumble dryer cycle", 9_000_000.0, "2.5 kWh, a condenser dryer", "tumble dryer cycles"),
+    Comparator("kilometre driven in an electric car", 648_000.0, "0.18 kWh/km", "kilometres driven in an electric car"),
+    Comparator("day of a fridge", 3_456_000.0, "40 W average duty for 24 h", "days of a fridge"),
+    Comparator("day of a laptop in constant use", 4_320_000.0, "50 W for 24 h", "days of a laptop in constant use"),
+    Comparator("bath run", 7_060_000.0, "150 l from 10 C to 40 C at 90% immersion efficiency", "baths run"),
+    Comparator("mile driven in an electric car", 1_043_000.0, "0.18 kWh/km over 1.609 km", "miles driven in an electric car"),
+    # ---- filling the band a run actually lands in ------------------------
+    Comparator("second of a kettle at half power", 1500.0, "1.5 kW for 1 s", "seconds of a kettle at half power"),
+    Comparator("second of a hair dryer", 1800.0, "1.8 kW for 1 s", "seconds of a hair dryer"),
+    Comparator("second of a microwave", 1000.0, "1 kW for 1 s", "seconds of a microwave"),
+    Comparator("second of a vacuum cleaner", 900.0, "900 W for 1 s", "seconds of a vacuum cleaner"),
+    Comparator("second of a 55-inch TV", 100.0, "100 W for 1 s", "seconds of a 55-inch TV"),
+    Comparator("second of a games console", 200.0, "200 W for 1 s", "seconds of a games console"),
+    Comparator("second of a fridge compressor", 120.0, "120 W while running, for 1 s", "seconds of a fridge compressor"),
+    Comparator("minute of a phone charging", 1038.0, "17.3 Wh over about 100 minutes", "minutes of a phone charging"),
+    Comparator("minute of a games console", 12_000.0, "200 W for 60 s", "minutes of a games console"),
+    Comparator("minute of a fridge compressor", 7200.0, "120 W for 60 s", "minutes of a fridge compressor"),
+    Comparator("minute of a hair dryer", 108_000.0, "1.8 kW for 60 s", "minutes of a hair dryer"),
+    Comparator("minute of a vacuum cleaner", 54_000.0, "900 W for 60 s", "minutes of a vacuum cleaner"),
+    Comparator("minute of an oven", 120_000.0, "2 kW for 60 s", "minutes of an oven"),
+    Comparator("minute of a tumble dryer", 150_000.0, "2.5 kW for 60 s", "minutes of a tumble dryer"),
+    Comparator("minute of a fan heater", 120_000.0, "2 kW for 60 s", "minutes of a fan heater"),
+    Comparator("espresso pulled", 45_000.0, "1.4 kW machine for about 32 s including pre-heat share", "espressos pulled"),
+    Comparator("cafetiere of coffee", 167_400.0, "0.4 l from 20 C to 100 C in a kettle at 80%", "cafetieres of coffee"),
+    Comparator("hot water bottle filled", 313_950.0, "0.75 l from 20 C to 100 C in a kettle at 80%", "hot water bottles filled"),
+    Comparator("pan of pasta water boiled", 837_200.0, "2 l from 20 C to 100 C in a kettle at 80%", "pans of pasta water boiled"),
+    Comparator("slice of pizza reheated", 90_000.0, "1 kW microwave for 90 s", "slices of pizza reheated"),
+    Comparator("piece of bread toasted lightly", 48_000.0, "800 W toaster for 60 s", "pieces of bread toasted lightly"),
+    Comparator("kettle boiled full", 627_900.0, "1.5 l from 20 C to 100 C in a kettle at 80%", "kettles boiled full"),
+    Comparator("laptop charged from flat", 216_000.0, "60 Wh battery", "laptops charged from flat"),
+    Comparator("tablet charged from flat", 118_800.0, "33 Wh battery", "tablets charged from flat"),
+    Comparator("e-bike battery charged", 1_800_000.0, "500 Wh battery", "e-bike batteries charged"),
+    Comparator("cordless drill battery charged", 194_400.0, "54 Wh pack", "cordless drill batteries charged"),
+    Comparator("hour of a games console", 720_000.0, "200 W for 1 h", "hours of a games console"),
+    Comparator("hour of a set-top box", 28_800.0, "8 W for 1 h", "hours of a set-top box"),
+    Comparator("hour of a phone charger left plugged in", 1800.0, "0.5 W vampire draw for 1 h", "hours of a phone charger left plugged in"),
+    Comparator("hour of an electric blanket", 360_000.0, "100 W for 1 h", "hours of an electric blanket"),
+    Comparator("hour of a dehumidifier", 1_080_000.0, "300 W for 1 h", "hours of a dehumidifier"),
+    Comparator("hour of a fan heater", 7_200_000.0, "2 kW for 1 h", "hours of a fan heater"),
+    Comparator("hour of a heat pump", 3_600_000.0, "1 kW electrical input for 1 h", "hours of a heat pump"),
+    Comparator("hour of a server in a rack", 1_800_000.0, "500 W for 1 h", "hours of a server in a rack"),
+    Comparator("day of a wifi router", 518_400.0, "6 W for 24 h", "days of a wifi router"),
+    Comparator("day of a smart speaker", 259_200.0, "3 W for 24 h", "days of a smart speaker"),
+    Comparator("day of a games console left on", 17_280_000.0, "200 W for 24 h", "days of a games console left on"),
+    Comparator("week of a fridge", 24_192_000.0, "40 W average duty for 7 days", "weeks of a fridge"),
+    Comparator("month of a wifi router", 15_768_000.0, "6 W for 30.4 days", "months of a wifi router"),
+    Comparator("10 km drive in an electric car", 6_480_000.0, "0.18 kWh/km x 10", "10 km drives in an electric car"),
+    Comparator("100 km drive in an electric car", 64_800_000.0, "0.18 kWh/km x 100", "100 km drives in an electric car"),
+    Comparator("litre of petrol burnt", 34_200_000.0, "9.5 kWh of chemical energy per litre", "litres of petrol burnt"),
+    Comparator("bag of coal burnt", 700_000_000.0, "25 kg at about 28 MJ/kg", "bags of coal burnt"),
+    Comparator("month of a UK home", 821_000_000.0, "2739 kWh a year, divided by twelve", "months of a UK home"),
+    Comparator("hour of a domestic solar array at noon", 14_400_000.0, "4 kWp array for 1 h", "hours of a domestic solar array at noon"),
+    Comparator("day of a domestic solar array", 43_200_000.0, "about 12 kWh on a good summer day", "days of a domestic solar array"),
+    Comparator("year of a fridge", 1_261_440_000.0, "40 W average duty for a year", "years of a fridge"),
+    Comparator("lifetime of a AAA battery", 5400.0, "1000 mAh x 1.5 V", "lifetimes of a AAA battery"),
+    Comparator("kilogram lifted to the top of Big Ben", 957.0, "1 kg x 9.81 x 96 m", "kilograms lifted to the top of Big Ben"),
+    # ---- 100 MJ upwards: fleets, and the honest top of the scale ---------
+    Comparator("day of a UK home", 27_000_000.0, "7.5 kWh, Ofgem typical domestic consumption", "days of a UK home"),
+    Comparator("week of a UK home", 189_000_000.0, "7.5 kWh x 7", "weeks of a UK home"),
+    Comparator("full charge of an electric car", 216_000_000.0, "60 kWh battery", "full charges of an electric car"),
+    Comparator("year of a UK home", 9_860_000_000.0, "2739 kWh, Ofgem typical annual electricity", "years of a UK home"),
+)
+
+#: The comparator picker aims to put the figure inside this band, so the number
+#: in front of the label is one a person can picture. Below 0.1 the answer is
+#: "hardly any of one", above 100 it stops being a comparison.
+NICE_LOW = 0.1
+NICE_HIGH = 100.0
+
+
+def choose(joules: float, *, table: tuple[Comparator, ...] = COMPARATORS) -> tuple[Comparator, float] | None:
+    """The comparator that puts this figure closest to one whole unit.
+
+    Closest in log space, because 0.5 of a thing and 2 of a thing are equally
+    easy to picture and a linear distance would prefer the wrong one of them.
+    """
+
+    if not isinstance(joules, (int, float)) or isinstance(joules, bool):
+        return None
+    value = float(joules)
+    if value <= 0 or value != value or value in (float("inf"), float("-inf")):
+        return None
+    import math
+
+    best: tuple[Comparator, float] | None = None
+    best_distance = float("inf")
+    for entry in table:
+        if entry.joules <= 0:
+            continue
+        count = value / entry.joules
+        distance = abs(math.log10(count))
+        if distance < best_distance:
+            best, best_distance = (entry, count), distance
+    return best
+
+
+def _round_count(count: float) -> str:
+    if count >= 100:
+        return f"{count:,.0f}"
+    if count >= 10:
+        return f"{count:.0f}"
+    if count >= 1:
+        return f"{count:.1f}".rstrip("0").rstrip(".")
+    if count >= 0.1:
+        return f"{count:.2f}".rstrip("0").rstrip(".")
+    return f"{count:.3f}".rstrip("0").rstrip(".")
+
+
+def describe(joules: float) -> str:
+    """"about 1.4 mugs of tea boiled", or an empty string if there is nothing to say."""
+
+    chosen = choose(joules)
+    if chosen is None:
+        return ""
+    entry, count = chosen
+    if count < 0.01:
+        return f"a tiny fraction of {_article(entry.label)}"
+    return f"about {_round_count(count)} {entry.name(count)}"
+
+
+def _article(label: str) -> str:
+    return ("an " if label[:1].lower() in "aeiou" else "a ") + label
+
+
+def basis(joules: float) -> str:
+    """The working behind whichever comparator was shown."""
+
+    chosen = choose(joules)
+    return "" if chosen is None else chosen[0].note

distinct_server/presentation.py

@@ -826,6 +826,11 @@ footer,.gradio-container footer{display:none !important;}
 .c-usage--absent .c-usage__figure{color:var(--c-muted) !important; font-size:18px;}
 .c-usage__means{margin:2px 0 0; font-size:var(--t-micro); color:var(--c-sage-dark) !important;
                 line-height:1.45;}
+/* The exact span sits under the familiar comparison, quieter than it: the
+   first line is what a reader takes away, the second is what they check it
+   against. */
+.c-usage__span{margin:0; font-size:var(--t-micro); color:var(--c-muted) !important;
+               line-height:1.45;}
 .c-usage--absent .c-usage__means{color:var(--c-muted) !important; font-style:italic;}
 .c-usage__detail{margin:3px 0 0; font-size:11px; color:var(--c-muted) !important; line-height:1.45;}
 .c-usage__more{margin-top:var(--s3); border-top:1px solid var(--c-hairline) !important;

distinct_server/render.py

@@ -36,6 +36,8 @@ from html import escape
 from pathlib import Path
 from typing import Optional
 
+from . import comparators as _comparators
+
 __all__ = [
     "activity",
     "assessment_legend",
@@ -978,8 +980,21 @@ def energy_headline(
             f'<p class="c-usage__means">{esc(absent_reason or "not measured, and not counted as zero")}</p>'
             "</div>"
         )
-    means = comparator(joules)
-    means_html = f'<p class="c-usage__means">{esc(means)}</p>' if means else ""
+    # TWO COMPARISONS, BECAUSE THEY ANSWER DIFFERENT QUESTIONS.
+    #
+    # "about 1.4 mugs of tea boiled" is the one people actually read: a whole
+    # familiar thing, and how much of it this is. "about 12 seconds of a 10 W
+    # bulb" is exact and stays underneath it, because for very small figures a
+    # fraction of a mug of tea means nothing and a span of time still does.
+    equals = _comparators.describe(joules)
+    span = comparator(joules)
+    means_html = f'<p class="c-usage__means">{esc(equals)}</p>' if equals else ""
+    if span and span != equals:
+        basis = _comparators.basis(joules)
+        # The working travels with the comparison. Somebody who wants to check
+        # "one mug of tea is 105 kJ" can, without leaving the page.
+        title = f' title="{esc(basis)}"' if basis else ""
+        means_html += f'<p class="c-usage__span"{title}>{esc(span)}</p>'
     detail_html = f'<p class="c-usage__detail">{esc(detail)}</p>' if detail else ""
     return (
         '<div class="c-usage">'
@@ -1005,11 +1020,19 @@ def format_joules_per_token(value: float) -> str:
 def format_joules(joules: float) -> str:
     """A figure with a unit people read without converting.
 
-    Joules below a kilojoule, kilojoules above. Watt-hours are not used as the
-    headline: a run costs hundredths of one, and a number that starts 0.00 is
-    read as zero however it is labelled.
+    Every three decades gets its own prefix. This used to stop at kilojoules,
+    so a worker's lifetime total rendered as "870000.00 kJ" -- six digits and a
+    prefix, which is the exact thing a prefix exists to prevent. A session
+    figure and a fleet figure are decades apart and both have to be readable.
+
+    Watt-hours are not used as the headline: one run costs hundredths of one,
+    and a number that starts 0.00 reads as zero however it is labelled.
     """
 
+    if joules >= 1_000_000_000:
+        return f"{joules / 1_000_000_000:.2f} GJ"
+    if joules >= 1_000_000:
+        return f"{joules / 1_000_000:.2f} MJ"
     if joules >= 1_000:
         return f"{joules / 1_000:.2f} kJ"
     if joules >= 10:

distinct_server/ui.py

@@ -741,16 +741,30 @@ def _measurement_note(readings: Sequence[EnergyReading]) -> str:
     if providers:
         parts.append("Measured by: " + ", ".join(providers) + ".")
     parts.append(
-        "Measured figures come from hardware counters: Intel RAPL, NVIDIA NVML "
-        "or nvidia-smi, Apple silicon package counters. Modelled figures come "
-        "from CPU busy-time and say so in their scope. The two are never added "
-        "together, because different scopes answer different questions."
+        "Every figure is a hardware counter reading. There is no model and no "
+        "estimate: a component either has a counter the worker can read, or it "
+        "is named as absent and no number is invented for it."
+    )
+    parts.append(
+        "On an NVIDIA GPU the driver keeps a running energy register in "
+        "millijoules (NVML, Volta and later), so a run's energy is the exact "
+        "difference between two reads, with no sampling. Older boards integrate "
+        "board power on a 50 ms timer instead and say so. CPU package energy "
+        "comes from RAPL: the powercap interface on Linux, and on Windows the "
+        "Energy Meter counter read through PDH. Where a machine has both, both "
+        "are read over the same window and added."
     )
     parts.append(
         "Where the runner reported real token counts, each answer also shows "
         "joules per generated token. Token counts are never estimated from "
         "characters."
     )
+    parts.append(
+        "What no counter can see is not guessed at: power-supply loss, fans, "
+        "storage and the mainboard are real electricity that no multiplier is "
+        "applied to reach. The figure is therefore a floor for the machine's "
+        "true draw, covering exactly the components named in the scope."
+    )
     parts.append(
         "Agent-mode runs cost more than generation alone: tool calls and the "
         "safety screen are separate passes, and the guard's cost is recorded "

pyproject.toml

@@ -27,6 +27,14 @@ dependencies = [
     "cryptography>=42",
     "gradio_client==2.6.0",
     "pyRAPL==0.2.3.1; sys_platform == 'linux'",
+    # NVIDIA GPU energy. For inference on a graphics card this is nearly all of
+    # the energy a run costs, so it is a base dependency rather than an extra:
+    # a worker that silently measured only its CPU package would understate a
+    # GPU run by roughly an order of magnitude while still calling the figure
+    # measured. The library is a thin ctypes binding to the driver's own NVML
+    # and installs on machines with no NVIDIA hardware, where it simply reports
+    # that there is none.
+    "nvidia-ml-py>=12.535",
     # The worker's own screen. Pinned rather than ranged because the frozen
     # build has to be reproducible, and because a Textual minor release can
     # change how a widget lays out, which is a visual regression no test in

tests/test_comparators.py

@@ -0,0 +1,116 @@
+"""The comparison under a figure has to be right, or it undoes the figure.
+
+A wrong comparator is worse than none: the number above it is measured, and a
+reader who catches the comparison being wrong has no reason to trust the
+measurement either.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+
+from distinct_server.comparators import (
+    COMPARATORS,
+    KETTLE_EFFICIENCY,
+    KWH,
+    WATER_SPECIFIC_HEAT,
+    basis,
+    choose,
+    describe,
+)
+
+
+def test_there_are_about_a_hundred_of_them() -> None:
+    assert len(COMPARATORS) >= 100
+
+
+def test_every_entry_states_its_working() -> None:
+    for entry in COMPARATORS:
+        assert entry.note.strip(), entry.label
+        assert entry.joules > 0, entry.label
+        assert math.isfinite(entry.joules), entry.label
+
+
+def test_labels_are_unique() -> None:
+    labels = [entry.label for entry in COMPARATORS]
+    assert len(labels) == len(set(labels))
+
+
+def test_the_physics_is_the_physics() -> None:
+    """Spot-check the derived entries against the formula in the docstring."""
+
+    by_label = {entry.label: entry.joules for entry in COMPARATORS}
+
+    # 0.25 l from 20 C to 100 C, in a kettle at 80%.
+    expected = 0.25 * WATER_SPECIFIC_HEAT * 80 / KETTLE_EFFICIENCY
+    assert by_label["mug of tea boiled"] == pytest.approx(expected, rel=0.01)
+
+    # 0.568 l (a pint) over the same rise.
+    expected = 0.568 * WATER_SPECIFIC_HEAT * 80 / KETTLE_EFFICIENCY
+    assert by_label["pint of water boiled"] == pytest.approx(expected, rel=0.01)
+
+    # 1 kg of water, 1 degree.
+    assert by_label["litre of water warmed by 1 C"] == pytest.approx(WATER_SPECIFIC_HEAT, rel=0.001)
+
+    # A 100 g apple lifted a metre.
+    assert by_label["apple lifted one metre"] == pytest.approx(0.1 * 9.81, rel=0.01)
+
+    # Rated appliances are watts times seconds.
+    assert by_label["minute in a microwave"] == pytest.approx(1000 * 60)
+    assert by_label["hour of a laptop"] == pytest.approx(50 * 3600)
+    assert by_label["load of washing"] == pytest.approx(0.7 * KWH, rel=0.001)
+    assert by_label["day of a UK home"] == pytest.approx(7.5 * KWH, rel=0.001)
+
+
+def test_a_figure_always_finds_a_comparison_it_can_carry() -> None:
+    """Across nine decades, the count in front of the label stays picturable."""
+
+    value = 1.0
+    while value <= 1e10:
+        chosen = choose(value)
+        assert chosen is not None, value
+        _, count = chosen
+        assert 0.05 <= count <= 20, (value, count)
+        value *= 3.0
+
+
+def test_the_chosen_comparison_is_the_closest_one() -> None:
+    entry, count = choose(104_650.0)
+    assert entry.label == "mug of tea boiled"
+    assert count == pytest.approx(1.0, rel=0.01)
+
+
+def test_singular_only_when_it_reads_as_one() -> None:
+    """"about 0.98 minute" reads as a mistake, so the rule follows the printed
+    number rather than a tolerance around 1.0."""
+
+    entry = next(e for e in COMPARATORS if e.label == "mug of tea boiled")
+    assert entry.name(1.0) == "mug of tea boiled"
+    assert entry.name(1.04) == "mug of tea boiled"
+    assert entry.name(0.98) == "mugs of tea boiled"
+    assert entry.name(2.0) == "mugs of tea boiled"
+    assert entry.name(0.4) == "mugs of tea boiled"
+    assert describe(104_650.0) == "about 1 mug of tea boiled"
+
+
+def test_nothing_sensible_to_say_says_nothing() -> None:
+    for bad in (0, -1, None, float("nan"), float("inf"), True, "12"):
+        assert describe(bad) == ""  # type: ignore[arg-type]
+        assert choose(bad) is None  # type: ignore[arg-type]
+
+
+def test_the_working_travels_with_the_comparison() -> None:
+    assert "4186" in basis(4186.0) or "kg" in basis(4186.0)
+    assert basis(104_650.0)
+
+
+def test_no_conversion_this_project_refuses_to_make() -> None:
+    """No CO2, water, land or money: those need assumptions a joule does not."""
+
+    forbidden = ("co2", "carbon", "gco2", "water footprint", "litres of water used", "£", "$")
+    for entry in COMPARATORS:
+        blob = f"{entry.label} {entry.note}".lower()
+        for word in forbidden:
+            assert word not in blob, (entry.label, word)

tests/test_energy_measurement.py

@@ -0,0 +1,252 @@
+"""The energy figure is the product, so these are the tests that matter most.
+
+Two properties are load-bearing and everything else follows from them:
+
+* a reported figure is a hardware counter reading, never a model, and
+* a component that could not be read is named rather than silently dropped.
+"""
+
+from __future__ import annotations
+
+import itertools
+
+import pytest
+
+from distinct_agent.energy import (
+    CompositeEnergyMeter,
+    EnergyUsage,
+    NvmlGpuEnergyMeter,
+    UnavailableEnergyMeter,
+    detect_energy_meter,
+)
+
+
+class FakeNvml:
+    """An NVML that behaves like the real one, including its awkward parts."""
+
+    def __init__(
+        self,
+        *,
+        devices: int = 1,
+        energy_counter: bool = True,
+        energy_series: list[float] | None = None,
+        power_watts: float = 100.0,
+        names: list[bytes] | None = None,
+    ) -> None:
+        self.devices = devices
+        self.energy_counter = energy_counter
+        # Millijoules, as NVML reports them.
+        self._energy = itertools.count(0, 1_000_000) if energy_series is None else iter(energy_series)
+        self._fixed: list[float] | None = energy_series
+        self.power_watts = power_watts
+        self.names = names or [b"NVIDIA GeForce RTX 4090"] * devices
+        self.started = False
+        self.shutdown_called = False
+
+    def nvmlInit(self):  # noqa: N802
+        self.started = True
+
+    def nvmlShutdown(self):  # noqa: N802
+        self.shutdown_called = True
+
+    def nvmlDeviceGetCount(self):  # noqa: N802
+        return self.devices
+
+    def nvmlDeviceGetHandleByIndex(self, index):  # noqa: N802
+        return f"handle-{index}"
+
+    def nvmlDeviceGetName(self, handle):  # noqa: N802
+        return self.names[int(str(handle).rsplit("-", 1)[1])]
+
+    def nvmlDeviceGetTotalEnergyConsumption(self, handle):  # noqa: N802
+        if not self.energy_counter:
+            raise RuntimeError("Not Supported")
+        return next(self._energy)
+
+    def nvmlDeviceGetPowerUsage(self, handle):  # noqa: N802
+        return int(self.power_watts * 1000)
+
+
+def test_the_energy_counter_is_an_exact_difference() -> None:
+    """Volta and later expose an integrating register; use it, do not sample."""
+
+    # Two reads per call (probe at construction, then start, then stop).
+    nvml = FakeNvml(energy_series=[0, 5_000, 12_000])
+    meter = NvmlGpuEnergyMeter(nvml=nvml, monotonic=iter([0.0, 2.0]).__next__)
+    assert meter.available
+    assert "energy-counter" in meter.scope
+
+    token = meter.start()
+    usage = meter.stop(token)
+    assert usage.available
+    # 12 J - 5 J, in joules, from millijoules.
+    assert usage.joules == pytest.approx(7.0)
+    assert usage.average_watts == pytest.approx(3.5)
+
+
+def test_a_counter_that_went_backwards_is_refused() -> None:
+    """A driver reload resets the register. That is not negative energy."""
+
+    nvml = FakeNvml(energy_series=[0, 9_000, 10])
+    meter = NvmlGpuEnergyMeter(nvml=nvml, monotonic=iter([0.0, 1.0]).__next__)
+    usage = meter.stop(meter.start())
+    assert not usage.available
+    assert usage.joules is None
+    assert "reset" in (usage.reason or "")
+
+
+def test_every_board_is_summed() -> None:
+    """A model split across two cards spent the energy of both."""
+
+    nvml = FakeNvml(devices=2, energy_series=[0, 0, 1_000, 1_000, 3_000, 4_000])
+    meter = NvmlGpuEnergyMeter(nvml=nvml, monotonic=iter([0.0, 1.0]).__next__)
+    assert "2 boards" in meter.scope
+    usage = meter.stop(meter.start())
+    # (3 - 1) + (4 - 1)
+    assert usage.joules == pytest.approx(5.0)
+
+
+def test_a_pre_volta_board_samples_power_and_says_so() -> None:
+    nvml = FakeNvml(energy_counter=False, power_watts=60.0)
+    meter = NvmlGpuEnergyMeter(nvml=nvml, sample_interval=0.01)
+    assert meter.available
+    assert "power-sampled" in meter.scope
+    import time as _time
+
+    token = meter.start()
+    _time.sleep(0.25)
+    usage = meter.stop(token)
+    assert usage.available
+    # 60 W for about a quarter second. Generous bounds: this is a real thread.
+    assert 6.0 < usage.joules < 25.0
+
+
+def test_no_nvidia_hardware_is_an_absence_with_a_reason() -> None:
+    class NoDevices(FakeNvml):
+        def nvmlDeviceGetCount(self):  # noqa: N802
+            return 0
+
+    meter = NvmlGpuEnergyMeter(nvml=NoDevices())
+    assert not meter.available
+    assert "no NVIDIA GPU" in (meter.unavailable_reason or "")
+
+
+def test_a_missing_library_never_raises() -> None:
+    """A worker without nvidia-ml-py must still start."""
+
+    meter = NvmlGpuEnergyMeter(nvml=None)
+    assert isinstance(meter.available, bool)
+    if not meter.available:
+        assert meter.unavailable_reason
+
+
+# -- composition ------------------------------------------------------------
+
+
+class StubMeter:
+    def __init__(self, provider: str, scope: str, joules: float | None, available: bool = True):
+        self.provider = provider
+        self.scope = scope
+        self.available = available
+        self.unavailable_reason = None if available else "stub is off"
+        self._joules = joules
+        self._id = provider
+
+    def start(self):
+        from distinct_agent.energy import EnergyToken
+
+        return EnergyToken(self._id, self.provider, self.scope, 0.0, self.available)
+
+    def stop(self, token):
+        if self._joules is None:
+            return EnergyUsage(self.provider, self.scope, False, 1.0, None, None, "no reading")
+        return EnergyUsage(self.provider, self.scope, True, 1.0, self._joules, self._joules)
+
+
+def test_components_are_summed_and_both_named() -> None:
+    meter = CompositeEnergyMeter(
+        [StubMeter("nvidia-nvml", "gpu-nvidia-energy-counter", 300.0),
+         StubMeter("rapl-powercap", "cpu-package", 40.0)],
+        monotonic=iter([0.0, 2.0]).__next__,
+    )
+    usage = meter.stop(meter.start())
+    assert usage.joules == pytest.approx(340.0)
+    assert "gpu-nvidia-energy-counter" in usage.scope
+    assert "cpu-package" in usage.scope
+    assert usage.average_watts == pytest.approx(170.0)
+
+
+def test_a_silent_component_is_named_not_dropped() -> None:
+    """A total missing its GPU must be distinguishable from one that had none."""
+
+    meter = CompositeEnergyMeter(
+        [StubMeter("nvidia-nvml", "gpu", None), StubMeter("rapl", "cpu-package", 40.0)],
+        monotonic=iter([0.0, 1.0]).__next__,
+    )
+    usage = meter.stop(meter.start())
+    assert usage.available
+    assert usage.joules == pytest.approx(40.0)
+    assert "nvidia-nvml" in (usage.reason or "")
+
+
+def test_a_component_with_no_counter_at_all_is_recorded_as_missing() -> None:
+    meter = CompositeEnergyMeter(
+        [StubMeter("nvidia-nvml", "gpu", 100.0)],
+        missing=["cpu package (Windows counter unavailable)"],
+        monotonic=iter([0.0, 1.0]).__next__,
+    )
+    usage = meter.stop(meter.start())
+    assert "cpu package" in (usage.reason or "")
+
+
+def test_no_component_reporting_is_an_absence_never_a_zero() -> None:
+    meter = CompositeEnergyMeter(
+        [StubMeter("a", "x", None), StubMeter("b", "y", None)],
+        monotonic=iter([0.0, 1.0]).__next__,
+    )
+    usage = meter.stop(meter.start())
+    assert not usage.available
+    assert usage.joules is None
+
+
+def test_nothing_available_is_an_absence_with_a_reason() -> None:
+    meter = CompositeEnergyMeter([], monotonic=iter([0.0, 1.0]).__next__)
+    assert not meter.available
+    usage = meter.stop(meter.start())
+    assert usage.joules is None
+    assert usage.reason
+
+
+# -- the ladder itself ------------------------------------------------------
+
+
+def test_an_unknown_platform_measures_nothing_rather_than_guessing() -> None:
+    meter = detect_energy_meter(system="Haiku")
+    assert isinstance(meter, UnavailableEnergyMeter)
+    assert not meter.available
+    usage = meter.stop(meter.start())
+    assert usage.joules is None
+
+
+def test_there_is_no_modelled_backend_left() -> None:
+    """The 12.5 W/core constant must not come back by any route."""
+
+    import distinct_agent.energy as energy
+
+    assert not hasattr(energy, "CpuLoadModelMeter")
+    assert not hasattr(energy, "DEFAULT_MODEL_WATTS_PER_BUSY_CORE")
+    source = __import__("pathlib").Path(energy.__file__).read_text()
+    # The constant may appear only in prose explaining why it is gone, never
+    # in an expression that could produce a figure.
+    assert "watts_per_busy_core" not in source
+    # The number may survive only in the prose explaining its removal, never
+    # anywhere it could be multiplied by anything.
+    for line in source.splitlines():
+        if "12.5" in line:
+            assert line.lstrip().startswith("#"), line
+
+
+def test_a_reported_figure_is_never_zero_for_an_unmeasured_window() -> None:
+    for meter in (UnavailableEnergyMeter("no counter"), CompositeEnergyMeter([])):
+        usage = meter.stop(meter.start())
+        assert usage.joules is None, "an absence must never render as 0 J"