fca3f76e51
The monorepo's IOReport energy backends now decline unless the CPU energy rail keeps advancing: on macOS 27 an unprivileged reader sees the CPU rails frozen or republished only in rare lumps, so a meter that trusted a present counter reported CPU work as GPU-only energy, or as zero, while tagging it a reading. The owner's decision is that a vendor energy counter is a real reading (the trust gap is provenance, not accuracy), so a LIVE reading is graded as a hardware reading, and every spec that grades vendor counters now carries the same rule: A reading from a vendor energy counter (RAPL, NVML, Apple IOReport, ...) MAY be graded as a hardware reading only while the counter is demonstrably live for the domain the figure claims: the implementation MUST have observed the counter covering that domain advance under load (for Apple IOReport: the CPU energy rail itself advancing in at least 5 sample intervals, in at least 4 of every 5, over at least 300 ms while the probing thread burns CPU). A counter that is present but not live - frozen, or republished in lumps - MUST NOT produce a hardware-graded figure; the implementation falls back to its estimator or reports the work unmetered, and SHOULD record why. A figure MUST NOT claim coverage of a domain its counter does not read; where the format has a coverage field, such a figure is Partial. Joule Code - spec/receipt.md §2 (REQUIRED): HwShunt now reads "an external shunt, or a vendor energy counter (RAPL, NVML, Apple SMC/IOReport) while that counter is live"; the rule above is added verbatim, and in this receipt the hardware grade is a present measured_uj and the HwShunt tag, so a counter that is not live supplies neither. The §1 comment and §5 say "live". - SPEC.md §6: the provenance definition now names IOReport and NVML beside RAPL/SMC, measured_uj comes only from an interface live for the domain it claims, and a paragraph states the MAY/MUST NOT, pointing to receipt.md §2 for the test. The §9 readiness row says "live" and "not live". - ROADMAP.md v0.2 "Measured energy": a vendor counter feeds the HwShunt path only while live; where it is present but not live (IOReport's CPU rails to an unprivileged reader on macOS 27) the receipt stays on the estimator. - examples/l3-jouleclaw/README.md: the claim that the receipt is "a real local measurement ... (HwShunt on RAPL/NVML hosts; Estimator on Apple Silicon until IOReport is wired)" was wrong both ways: run.rs wires only Apple Silicon's counter, and other hosts fall to the token Estimator. It now says so, that the counter's own tag is carried, and that HwShunt needs a live counter. - joule-code-receipt: the Provenance::HwShunt doc comment says the same. - CHANGELOG.md [Unreleased] ### Changed: the rule; no wire or vector change. Sense - SPEC.md §7 (REQUIRED): measured_uj comes only from a live interface; the rule is added verbatim. The Sandbox PowerMeter was described as "(real RAPL/IOReport)"; it is now described as grading a reading HwShunt only while its counter is live and falling back to its estimator otherwise, which is what origin/sandbox-meter/cpu-rail-liveness implements. §10's Sandbox edge says the same in brief. - sense-schema: the HwShunt, Energy and Energy::measured doc comments say a vendor counter is a hardware reading only while live. - Sense keeps no CHANGELOG, so none is added. Other specs that grade vendor counters - map/spec/receipt.md §2: the HwShunt row read "RAPL/SMC/shunt"; it now names a counter "while it is live", and the rule is added verbatim, noting that Receipt::seal cannot check liveness (the meter's duty, upstream). map/SPEC.md §6 states the MUST NOT and points there. CHANGELOG.md gains an [Unreleased] ### Changed entry; no wire or vector change. - arl/ARL-S.md, Telemetry: physical telemetry is what gates tiers above 0, and it said energy is "measured directly via RAPL ... NVML". The rule is added in ARL-S's own terms and lower-case keywords (ARL uses no RFC 2119 capitals): a counter that is not live does not produce physical telemetry, the energy it would have covered is reported unmetered, and the Supervisor must have observed the counter advance. No version bump. - smart-byte treatise §8.6: "Where RAPL or equivalent hardware energy counters are available, the measurement is read from the hardware" now requires the counter to be demonstrably live, and a frozen or lump- republished counter yields the same honest zero as an absent one. Text and doc comments only: no code path, wire format, or conformance vector changes. joule-code-rs (joule-code-receipt, joule-code-conformance) and sense-rs (sense-schema, sense-conformance) build and test clean, their rustdoc builds under -D warnings, map-rs (map-receipt, map-conformance) tests pass, `joule-code-conformance verify ../conformance/v1` passes 24/0/0, the no-vanity-metrics check passes, and every relative link in the changed Markdown resolves. Co-Authored-By: Claude Opus 5.5 <[email protected]>
73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
# Joule Code — The Receipt
|
|
|
|
Normative sub-specification of [`../SPEC.md`](../SPEC.md) §6. CC-BY-4.0.
|
|
|
|
Every coding operation carries a **receipt**: a signed, two-part energy record carried in a Joule Wire Protocol (JWP) frame. The receipt is the falsifiable cost basis of the operation — not its market price, but its honest energy cost.
|
|
|
|
## 1. Structure
|
|
|
|
```
|
|
Receipt {
|
|
op_id: ContentId,
|
|
tier: Tier,
|
|
energy: Energy,
|
|
sequence: u64,
|
|
nonce: [u8; 8],
|
|
sig: [u8; 64], // Ed25519 over the energy preimage (§3)
|
|
}
|
|
|
|
Energy {
|
|
measured_uj: Option<u64>, // present ONLY when from a live hardware interface (§2)
|
|
estimated_uj: u64, // always present
|
|
provenance: Provenance,
|
|
}
|
|
|
|
Provenance = HwShunt | ModelBased | Estimator
|
|
```
|
|
|
|
## 2. The provenance contract (REQUIRED)
|
|
|
|
The `Provenance` tag states how honest the figure is, and the spec never claims more than the platform delivers:
|
|
|
|
- `HwShunt` — read from a hardware energy interface: an external shunt, or a vendor energy counter (RAPL, NVML, Apple SMC/IOReport) while that counter is live for the domain the figure claims (below). A reading tagged `HwShunt` **MUST** have `measured_uj = Some`.
|
|
- `ModelBased` — computed from a calibrated per-operation energy model. `measured_uj` **MAY** be absent.
|
|
- `Estimator` — a coarse constant estimator (e.g. per-token coefficients applied to L4 token counts). `measured_uj` **MUST** be absent.
|
|
|
|
A runtime **MUST NOT** populate `measured_uj` from anything but a hardware interface, and **MUST NOT** tag a reading `HwShunt` without a present `measured_uj`. Absence is the honest answer when the platform cannot measure.
|
|
|
|
**Vendor counters.** A reading from a vendor energy counter (RAPL, NVML, Apple IOReport, ...) **MAY** be graded as a hardware reading only while the counter is demonstrably live for the domain the figure claims: the implementation **MUST** have observed the counter covering that domain advance under load (for Apple IOReport: the CPU energy rail itself advancing in at least 5 sample intervals, in at least 4 of every 5, over at least 300 ms while the probing thread burns CPU). A counter that is present but not live — frozen, or republished in lumps — **MUST NOT** produce a hardware-graded figure; the implementation falls back to its estimator or reports the work unmetered, and **SHOULD** record why. A figure **MUST NOT** claim coverage of a domain its counter does not read; where the format has a coverage field, such a figure is Partial.
|
|
|
|
In this receipt the hardware grade is a present `measured_uj` and the `HwShunt` tag: a counter that is present but not live supplies neither.
|
|
|
|
## 3. Signed form — JCR-1 (v0.2)
|
|
|
|
As of v0.2 the receipt's signed form is a **JCR-1 envelope** (SPEC §6.1), the signed-receipt format shared across the Transaction Science family — not a bespoke preimage. A Joule Code receipt therefore verifies under the family's existing JCR-1 tooling and its cross-language (Python/Go) reference verifiers.
|
|
|
|
```
|
|
core = canonical-det-CBOR( # RFC 8949 §4.2.1, length-first keys
|
|
{ jc_receipt: "joule-code/1", op_id, tier, estimated_uj,
|
|
measured_uj?, energy_provenance, sequence, nonce, steward } )
|
|
envelope = COSE_Sign1( # RFC 9052, EdDSA -8
|
|
protected = { 1: -8, 4: bstr(steward) },
|
|
payload = core,
|
|
signature = Ed25519_sign(endpoint_secret, Sig_structure) )
|
|
```
|
|
|
|
`Sig_structure` is `["Signature1", protected, external_aad(empty), core]` (RFC 9052 §4.4). Verification parses the tagged COSE_Sign1 (CBOR tag 18), rejects any `alg` but `-8`, rejects a `kid` other than the expected steward, checks the Ed25519 signature, and confirms the payload equals the receipt's canonical core. Sealing the receipt this way makes the cost basis non-repudiable by the endpoint that produced it and interoperable with every other family pillar.
|
|
|
|
> v0.1 used a bespoke `estimated_uj ‖ sequence ‖ nonce [‖ measured_uj]` preimage; v0.2 replaces it with JCR-1. This is the v0.1→v0.2 wire change.
|
|
|
|
## 4. The estimator of last resort (non-normative coefficients)
|
|
|
|
When only token counts are available — the common L4 case, where a remote ACP agent reports `input_tokens` / `output_tokens` but no energy — the estimator computes:
|
|
|
|
```
|
|
estimated_uj = input_tokens * J_IN_uj
|
|
+ output_tokens * J_OUT_uj
|
|
```
|
|
|
|
and tags the reading `Estimator`. The coefficients are **non-normative** and tunable; the reference consumer ships datacenter-scale defaults where output dominates prefill. Reference values (illustrative, not part of conformance): `J_IN_uj = 200_000`, `J_OUT_uj = 2_000_000` (i.e. 0.2 J / 2.0 J per token). The point of the standard is not the constant — it is that the figure is reported, signed, and honestly tagged as an estimate.
|
|
|
|
## 5. From estimated to measured
|
|
|
|
Promoting a tier's receipts from `Estimator` to `HwShunt`/`ModelBased` is the work item that turns the meter "real" (ROADMAP v0.2). The receipt schema does not change; only the `provenance` tag and the presence of `measured_uj` improve as the platform gains a hardware interface that is live for the work (§2). A consumer's UI **SHOULD** surface the provenance so a reader can tell a measured joule from an estimated one.
|