specs: a vendor counter is a hardware reading only while it is demonstrably live #119

Merged

dcharlot merged 5 commits from energy/liveness-must-specs into main 2026-10-01 05:51:28 -04:00

Conversation 0 Commits 5 Files changed 15 +126 -22

dcharlot commented 2026-09-30 20:01:17 -04:00

Owner

Copy link

Every spec that grades vendor energy counters now gets the same MUST. A counter's figure counts as a hardware reading only while the counter is demonstrably live for the domain the figure claims.

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.

Why. On macOS 27 an unprivileged reader sees IOReport's CPU energy rails republished only in rare lumps, sometimes in two steps. A meter that trusts a counter merely because the counter is present reports CPU work as GPU-only energy or as zero, and labels it a reading. Every spec below allowed exactly that. The vendor counter is still a real reading (the trust gap is provenance, not accuracy), but only while it moves.

What changed (text plus doc comments; no code paths, no vectors):

• joule-code
  • spec/receipt.md §2 (REQUIRED): HwShunt now covers a live vendor counter; the MUST is added.
  • SPEC.md §6: aligned with receipt.md, plus the §9 readiness row.
  • ROADMAP.md, the examples/l3-jouleclaw README, the joule-code-receipt HwShunt doc and a CHANGELOG note.
• sense
  • SPEC.md §7: the MUST, and the reference PowerMeter grades a reading HwShunt only while its counter is live (§10 too).
  • sense-schema doc comments.
• map
  • spec/receipt.md §2: the MUST, noting that Receipt::seal cannot check liveness.
  • SPEC.md §6 and a CHANGELOG entry.
• arl: ARL-S.md Telemetry gets the rule in ARL's own lower-case style. A counter that is not live gives no physical telemetry, and that energy is unmetered.
• smart-byte: treatise §8.6. A frozen or lump-refreshed counter gives the same honest zero as an absent one.

Verified.

• joule-code: the receipt and conformance tests pass, and joule-code-conformance verify gives 24/0/0.
• sense and map: the conformance packs pass.
• rustdoc under -D warnings is clean; the vanity-metrics check is clean; all 29 relative links resolve.

Merge after #114 and #117. Sense §7 describes the sandbox PowerMeter behaviour that #114 adds. #117 is where jouleclaw-energy grades a live IOReport reading the same way.

Left for a one-line follow-up: map-receipt's HwShunt doc comment ("RAPL/SMC/shunt").

Smart-byte spec/vector gate

The change to treatise §8.6 is editorial for the pack: the wire format and every vector stay the same. So the last commit records it under ## Editorial change log in smart-byte/conformance/v1/regeneration.md, as the gate's error message asks. The envelope and SAID vectors carry measured_microjoules as a fixed input (1200, 0 and 1). Their expected values depend on that number, not on how a node came to report it, so no vector changes.

Rebased onto main after #99 and #125 merged. The entry now sits first in their change log, and the branch merges cleanly.

🤖 Generated with Claude Code

Every spec that grades vendor energy counters now gets the same MUST. A counter's figure counts as a hardware reading only while the counter is **demonstrably live** for the domain the figure claims. > 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. **Why.** On macOS 27 an unprivileged reader sees IOReport's CPU energy rails republished only in rare lumps, sometimes in two steps. A meter that trusts a counter merely because the counter is present reports CPU work as GPU-only energy or as zero, and labels it a reading. Every spec below allowed exactly that. The vendor counter is still a real reading (the trust gap is provenance, not accuracy), but only while it moves. **What changed** (text plus doc comments; no code paths, no vectors): - **joule-code** - `spec/receipt.md` §2 (REQUIRED): HwShunt now covers a live vendor counter; the MUST is added. - `SPEC.md` §6: aligned with receipt.md, plus the §9 readiness row. - `ROADMAP.md`, the `examples/l3-jouleclaw` README, the `joule-code-receipt` HwShunt doc and a CHANGELOG note. - **sense** - `SPEC.md` §7: the MUST, and the reference PowerMeter grades a reading HwShunt only while its counter is live (§10 too). - `sense-schema` doc comments. - **map** - `spec/receipt.md` §2: the MUST, noting that `Receipt::seal` cannot check liveness. - `SPEC.md` §6 and a CHANGELOG entry. - **arl**: `ARL-S.md` Telemetry gets the rule in ARL's own lower-case style. A counter that is not live gives no physical telemetry, and that energy is unmetered. - **smart-byte**: treatise §8.6. A frozen or lump-refreshed counter gives the same honest zero as an absent one. **Verified.** - joule-code: the receipt and conformance tests pass, and `joule-code-conformance verify` gives 24/0/0. - sense and map: the conformance packs pass. - rustdoc under `-D warnings` is clean; the vanity-metrics check is clean; all 29 relative links resolve. **Merge after #114 and #117.** Sense §7 describes the sandbox PowerMeter behaviour that #114 adds. #117 is where jouleclaw-energy grades a live IOReport reading the same way. **Left for a one-line follow-up:** `map-receipt`'s HwShunt doc comment ("RAPL/SMC/shunt"). ### Smart-byte spec/vector gate The change to treatise §8.6 is editorial for the pack: the wire format and every vector stay the same. So the last commit records it under `## Editorial change log` in `smart-byte/conformance/v1/regeneration.md`, as the gate's error message asks. The envelope and SAID vectors carry `measured_microjoules` as a fixed input (1200, 0 and 1). Their expected values depend on that number, not on how a node came to report it, so no vector changes. Rebased onto `main` after #99 and #125 merged. The entry now sits first in their change log, and the branch merges cleanly. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-09-30 20:01:17 -04:00

specs: a vendor counter is a hardware reading only while it is demonstrably live ... 5f5d700bdf

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]>

dcharlot added 1 commit 2026-09-30 20:12:38 -04:00

map-receipt: HwShunt's doc says a vendor counter counts only while live ... 886c91f78d

The doc comment on Provenance::HwShunt still read "RAPL/SMC/shunt", with no
liveness condition. The map spec in the previous commit now says a counter
counts only while it is demonstrably live (receipt.md §2). This brings the
doc comment into line. Doc comment only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot added 1 commit 2026-09-30 20:20:53 -04:00

mesh: §3 grades a vendor counter HwShunt only while it is live ... c9e6fa5e42

Adds the shared liveness MUST to mesh SPEC §3, where Energy's provenance
coupling is defined. mesh/1 has no coverage field, so the section also
says a figure from a counter that does not cover the whole request, such
as a GPU counter on a host with no CPU counter, MUST NOT be graded HwShunt.
Text only. No vector changes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot referenced this pull request 2026-09-30 22:51:05 -04:00

jcp-energy: IOReport only when its CPU rail keeps advancing, never on a batch refresh #110

dcharlot referenced this pull request 2026-09-30 22:51:07 -04:00

proof-cascade: never meter CPU work through an IOReport CPU rail that does not keep moving #115

dcharlot referenced this pull request 2026-09-30 22:51:08 -04:00

eoc-meter: never build the IOReport counter on a CPU rail that does not keep moving #116

dcharlot referenced this pull request 2026-09-30 22:51:09 -04:00

jouleclaw-energy: IOReport only when its CPU rail keeps moving; consumers never zero-fill or relabel #117

dcharlot referenced this pull request 2026-09-30 22:51:48 -04:00

ci(standards-build): run all five IOReport meters on macOS, and fail a step whose test never ran (merge LAST) #102

dcharlot referenced this pull request 2026-09-30 23:03:57 -04:00

sandbox-meter: a CPU counter that does not keep moving is never a measurement, and no consumer relabels an estimate #114

dcharlot referenced this pull request from a commit 2026-09-30 23:09:12 -04:00

smart-byte: record the §8.6 liveness change as editorial

dcharlot added 1 commit 2026-09-30 23:09:12 -04:00

smart-byte: record the §8.6 liveness change as editorial ... 9f8bb00018

The spec/vector coupling gate failed #119: it changes
smart-byte/spec/ (treatise §8.6) without touching
smart-byte/conformance/. The change is editorial for the pack. It
narrows when a node may report a non-zero measured_microjoules, but
leaves the field, its encoding and every vector unchanged. Record that
in regeneration.md, as the gate asks.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot referenced this pull request from a commit 2026-10-01 01:10:54 -04:00

smart-byte: record the §8.6 liveness change as editorial

dcharlot force-pushed energy/liveness-must-specs from 9f8bb00018 to 2ed679bb6e 2026-10-01 01:10:55 -04:00 Compare

dcharlot added 1 commit 2026-10-01 01:22:33 -04:00

l3-jouleclaw README: leave the example's energy text to #117 ... 053a94bbc7

#117 rewrites this paragraph to say which counter the example reads on
each host and when its figure is measured. That already states the
liveness rule in full. This PR's edit of the same lines made the two
PRs conflict, whichever merged second. Drop it, so the two merge in
either order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot merged commit 7598ec9180 into main 2026-10-01 05:51:28 -04:00

dcharlot referenced this pull request from a commit 2026-10-01 05:51:30 -04:00

Merge pull request 'specs: a vendor counter is a hardware reading only while it is demonstrably live' (#119) from energy/liveness-must-specs into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!119

No description provided.