Going after the meters turned up a worse instance of a family this repo keeps
finding. `jouleclaw-omni/src/runtime/energy.rs` documents itself as measuring
"actual GPU, CPU, ANE and DRAM energy consumption in joules using Apple's
IOReport framework". It does not call IOReport. The macOS path multiplies
`getrusage` CPU seconds by a fixed 15 W; the other path multiplies wall-clock by
45 W; each then splits the result 60/20/20 across subsystems by constant
fractions. It has **zero tests**, and `runtime/mod.rs` does not declare it — so
it has never been compiled, by anything, ever.
That is the strongest member of the family. A feature-gated test with no
`--features` reports zero tests; a platform-gated meter on a single-platform
runner compiles out; a conformance suite in `main()` gets built and never run.
An orphan source file does not even type-check. It is invisible to cargo check,
cargo test, clippy and every conformance suite simultaneously, and it cannot
fail because nothing asks it anything.
The hazard is the next reader, not the dead code. A real meter with a per-rail
liveness gate already lives in the same workspace (`jouleclaw-energy`); someone
who trusts this file's header and wires it in instead gets CPU-seconds times a
guess, apportioned by invented fractions — energy derived from a performance
proxy, which is the thing the whole metering ladder exists to grade against.
So: `scripts/check-orphan-sources.py`, wired into the hygiene workflow. The
per-subsystem split is worth naming separately — four fields reading as four
independent observations when all four are fractions of one number is precision
standing in for measurement, and it invites conclusions nothing here supports.
**Measured, not estimated.** 1659 library sources checked; 25 orphans, all in
`jouleclaw-omni`, 19,964 lines never compiled. Every other crate is clean.
My first pass said 77 — it counted `src/bin/*.rs`, which cargo auto-discovers,
so the exclusions are part of the check rather than a convenience. The baseline
was then generated by the detector instead of retyped, because hand-copying it
pinned 15 of 25 and the check caught the other ten.
Falsified in both directions before being trusted, and the CI step repeats the
self-test on every run: a planted orphan must fail the check, and removing it
must pass. Exit codes verified without a pipe — `$?` after `| head` is head's
status, which is how a gate silently stops gating.
The baseline pins today's 25 so this does not go red on a pre-existing
condition, and names what the file falsely claims. Removing an entry is the
point; adding one is a regression to argue for in a commit message.
`energy.rs` itself gets a corrected header and nothing else. I had added a
declared `EnergyBasis` to it and reverted that: the field made the orphan stop
compiling, and a broken orphan is worse than an honest one. Whether those 25
files are wired up or deleted is not mine to decide — 20k lines is someone's
work, and the guard stops the problem growing either way.
Co-Authored-By: Claude Opus 5 <[email protected]>
104a8b444c