# 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/-.json` — one stub per major silicon lineage. Shipped EMPTY. A non-null `joules_uj_*` field is a *standing claim* by its author that the protocol in `PROTOCOL.md` was 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.