84768074ca
Some checks failed
energy meters on real hardware / RAPL and NVML on jetson-hub (push) Has been cancelled
energy meters on real hardware / sink decode table · RAPL on jetson-hub (NVML surveyed) (push) Has been cancelled
energy meters on real hardware / sink decode table · per-task energy and the GPU rail on macOS (push) Has been cancelled
repository checks / lockfiles, advisories, tests in CI, workflow hygiene, spec and section references, public text (push) Has been cancelled
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (push) Has been cancelled
joule-code conformance gate / joule-moq-relay, its own energy on a counter (macos) (push) Successful in 2m15s
wai-app and Create / wai-app · does this change touch it (push) Successful in 1m45s
wai-app and Create / wai-app · tests, clippy, the line language's verifier (linux) (push) Has been cancelled
wai-app and Create / wai-app · Create, browser end-to-end (macos) (push) Has been cancelled
joule-code conformance gate / Build + round-trip C1-C4 vectors (push) Successful in 5m43s
joule-code conformance gate / joule-moq-ingest, every target (push) Has been cancelled
joule-code conformance gate / joule-moq-relay, every target (push) Has been cancelled
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]>
84 lines
4 KiB
Markdown
84 lines
4 KiB
Markdown
# 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-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.
|