# JouleClaw vendor-energy measurement protocol

Honest energy accounting requires honest energy readings. The
[`EnergyCounter`] trait in this crate names three provenance tiers:

- **HwShunt** — a hardware reading: a shunt (board-level current
  sense, IPMI sensor), or a vendor energy counter (Intel/AMD RAPL
  MSR, NVML cumulative energy, Apple IOReport) while it is
  demonstrably live for the domain the figure claims — the
  measurer observed the counter covering that domain advance under
  load. A counter that is present but not live (frozen, or
  republished in lumps) gives no HwShunt figure. Authoritative.
- **ModelBased** — a vendor-published energy model (DCGM-X,
  NVML `power.draw`, vendor whitepapers) consulted at run time.
  Trustworthy if the model itself was validated by HwShunt.
- **Estimator** — anything derived from wall-clock × static
  power ceiling. Useful as a floor; never as a ceiling.

The circuit breaker is only as honest as the **worst** counter in a
request's span — a single Estimator reading taints the whole walk.
That is by design.

## Why this file exists

The trait + provenance taxonomy is one half of the honesty story.
The other half is **actual measured numbers** for specific silicon
under specific workloads, so an operator can compute the energy
cost of a cascade walk before issuing it. This document specifies
*how* a third party with vendor hardware produces those numbers in
a way the rest of the JouleClaw ecosystem can consume.

Per-vendor fixture files live in `vendors/`. Each one ships
**empty** — values are `null` until a measurement run fills them.
A fixture with non-null values is a *standing claim* by its author
that the numbers were produced by the protocol below.

## Measurement protocol (vendor-agnostic)

Every workload measurement MUST capture:

1. **Hardware identification** —
   `vendor`, `model`, `tdp_w` (datasheet), `host_os`.
2. **Counter** — which trait impl was used (`RaplCounter`,
   `NvmlCounter`, `AppleIoReportCounter`, `AppleSiliconMeter`, or a
   vendor-specific impl).
3. **Provenance** — `HwShunt` | `ModelBased` | `Estimator`. `HwShunt`
   only for a counter observed live over the run (for Apple IOReport,
   `ioreport_status()` returned `Live`); record in `method` how
   liveness was established.
4. **Resolution** — `resolution_uj` (smallest delta the counter
   meaningfully reports) and `min_window_ns` (smallest sampling
   window below which the reading is noise-dominated). Honest
   self-reporting; do not round below.
5. **Workload** — one of:
   - `idle_1s` — power draw with no workload for one second.
   - `tier_L0_lookup` — N = 10,000 keyed map lookups, no
     mathematics. Floor energy.
   - `tier_L1_local_index` — BM25 search over the seeded reference
     corpus (`jouleclaw-local-index`'s in-memory fixture).
   - `tier_L3_model_7b_token` — one decoded token of a 7B-param
     model at fp16 with a 64-token prompt. The token-energy
     baseline.
   - `tier_L3_model_70b_token` — same, at 70B-param fp16.
6. **Method** — `cold` (counter zeroed before the workload starts)
   or `warm` (counter sampled at workload boundaries).
7. **Joules per workload-unit** — `joules_uj_per_unit` for
   token-shaped workloads; `joules_uj_total` otherwise.
8. **Sample count** — `n_samples` and `stddev_uj` so consumers
   can reason about variance.
9. **Date** — ISO-8601 timestamp of the measurement run.
10. **Attestation** — `signed_by` (optional Ed25519 verifying key
    hex of the operator), `attestation_url` (optional URL to the
    public log entry / paper / blog post backing the claim).

## What a conformant fixture file looks like

See `vendors/intel-rapl-template.json` for the empty shape.
Every workload from §5 above MUST be measured (or explicitly
marked `"workload_not_run": true`); cherry-picking the favourable
ones isn't conformant. The whole point is to make the
expensive-tier-token energy visible alongside the floor.

## Why the fixtures ship empty

The workspace dev machine cannot produce HwShunt readings for
non-Intel CPU silicon, any NVIDIA GPU, any AMD GPU, any Apple
Silicon GPU, any TPU, or any Chinese accelerator. Pretending
otherwise — populating the 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 them, signs them, and PRs
them back. Anyone else holding the fixture-author's verifying key
can then verify the claim was actually made by that operator.

## Roadmap (not part of this conformance)

- A `jouleclaw-vendor-energy-attest` binary that takes a fixture
  JSON, signs it via Ed25519, and emits a wire-form attestation
  in the same shape as JCR-1 receipts (so the same Python/Go
  verifiers can audit it).
- A registry of community-contributed fixtures with conflict
  resolution (when two operators measure the same silicon and
  disagree, both are kept; consumers decide which to trust).
- Cross-vendor parity: at least one HwShunt fixture per major
  silicon lineage (Intel CPU / AMD CPU / NVIDIA GPU / AMD GPU /
  Apple Silicon / Cloud TPU / Huawei Ascend / Cambricon /
  Qualcomm Cloud AI).