84768074ca
The meters count an IOReport interval only within three of the probe's ticks, and the texts that state the rule said nothing of it, so an implementation following any of them would call a lump-refreshed rail live once load stretched its intervals. Each now says what an interval is (from one sample in hand to the next), that only one no longer than three of the probe's ticks (75 ms at its 25 ms tick) counts, that a longer one counts as nothing (not among the intervals, not as an advance, not towards the 300 ms), and that the 300 ms is the summed length of the intervals that count. The normative clauses in arl/ARL-S.md, jcp/SPEC.md, joule-code/spec/receipt.md, joule-ui/SPEC.md, jouleclaw/SPEC.md, JCR-1-spec.md, map/spec/receipt.md, mesh/SPEC.md (a block quote), proof/SPEC.md and sense/SPEC.md; proof-schema's quotation of proof/SPEC.md's; jouleclaw-energy's conformance README; and the proof and sandbox READMEs, which say the cap is IOReport's alone. Map's and Joule Code's unreleased changelog entries, which record the rule as it was added, are amended, since neither release has gone out. No wire or conformance-vector change. Co-Authored-By: Claude Opus 5.5 <[email protected]>
4 KiB
vendor-energy/1 — conformance
JouleClaw's energy honesty is a two-part claim: (a) the
EnergyCounter trait + Provenance taxonomy in code (in this
crate's src/), and (b) actual measured numbers from real silicon
under named workloads. This directory carries the second half.
Files
PROTOCOL.md— how a third party with vendor hardware produces the numbers. Read this first.vendors/template.json— empty fixture; the canonical shape every per-vendor fixture clones.vendors/<vendor>-<class>.json— one stub per major silicon lineage. Shipped EMPTY. A non-nulljoules_uj_*field is a standing claim by its author that the protocol inPROTOCOL.mdwas followed.
Inventory (empty stubs that need measurements)
| File | Counter | Provenance |
|---|---|---|
vendors/intel-cpu-rapl.json |
RaplCounter |
HwShunt |
vendors/amd-cpu-rapl.json |
RaplCounter |
HwShunt |
vendors/nvidia-gpu-nvml.json |
NvmlCounter |
HwShunt |
vendors/amd-gpu-rocm.json |
RocmSmiCounter |
HwShunt |
vendors/apple-silicon-ioreport.json |
AppleIoReportCounter |
HwShunt, while live (below) |
vendors/huawei-ascend-npu.json |
AscendSmiCounter |
HwShunt |
The Cloud TPU, Intel Gaudi, Cambricon, and Qualcomm Cloud AI classes are deliberately not yet stubbed — a stub commits to a counter trait impl, and the workspace doesn't ship one for those silicons today. Add the stub when the impl lands.
Why every fixture is empty
The workspace dev machine cannot produce HwShunt readings for any non-x86 CPU silicon or any accelerator. Filling these fixtures with numbers from blog posts or vendor whitepapers would corrupt the provenance contract the trait exists to enforce. Honest empty fixtures > dishonest filled ones.
A third party with the hardware fills a fixture, signs it via Ed25519, and PRs it back. Anyone holding the fixture-author's public key can verify the claim was actually made by that operator.
Verifier
cargo test -p jouleclaw-energy --test vendor_energy_conformance
The current verifier asserts every fixture is well-formed JSON
matching the schema. Once a fixture is filled (workload_not_run
flipped to false, numbers populated), the verifier will
additionally check internal consistency (idle ≤ tier_L0_lookup ≤
tier_L1_local_index ≤ tier_L3_model_*) and reject monotonicity
violations — the kind of misreporting that would otherwise sneak
past peer review.
Provenance — what each tier means
| Tag | What you're trusting | Use case |
|---|---|---|
HwShunt |
A hardware shunt, or a vendor energy counter (RAPL, NVML, Apple IOReport) while it is live for the domain it claims | Authoritative; the circuit breaker may use these directly. |
ModelBased |
A validated vendor energy model (DCGM-X, NVML power.draw) |
Trustworthy iff the model was validated against HwShunt elsewhere. |
Estimator |
Wall-clock × static TDP, or a hand-tuned heuristic | A floor, never a ceiling. The breaker treats Estimator as worst-case. |
A vendor energy counter's reading is a real reading; what a fixture must
pin down is its provenance, not its accuracy. A HwShunt figure in a
fixture is a claim that the counter was demonstrably live for the domain
the figure claims while the workload ran: the measurer observed the counter
covering that domain advance under load. For Apple IOReport that means
jouleclaw_energy::ioreport_status() was Live (the CPU energy rail
advanced in at least 5 sample intervals, in at least 4 of every 5, over at
least 300 ms while the probing thread burned CPU; an interval runs from when
one sample is in hand to when the next is, and only one no longer than three
of the probe's ticks, 75 ms at its 25 ms tick, counts: a longer one counts as
nothing, neither among the intervals, nor as an advance, nor towards the
300 ms, which is the summed length of the intervals that count). A counter that is present
but not live — frozen, or republished in lumps, as the CPU rails are for an
unprivileged reader on macOS 27.0.1 — gives no HwShunt figure; that run is
an Estimator run, or no run at all.