jouleclaw-energy: Implausible says what it now means, and a lint CI could not see #353

Merged

dcharlot merged 1 commit from fix/jouleclaw-energy-doc-links into main 2026-10-20 08:29:32 -04:00

Conversation 0 Commits 1 Files changed 3 +27 -7

dcharlot commented 2026-10-20 04:09:12 -04:00

Owner

Copy link

Three things in one crate, all found by reading cargo doc and clippy output that no CI step reads.

1. CounterLiveness::Implausible understated itself — my omission

#341 made the GPU plausibility bound two-sided, so the variant is now produced for a counter that accrues far less than its board's telemetry says it drew, as well as for one running faster than the board can draw. Its doc comment still described only the fast direction.

That is the defect family this crate keeps surfacing — documentation asserting something narrower than the code does — and here I introduced it. The doc now names both arms, and says which one matters at an energy ceiling: a counter reading low would otherwise be graded as hardware and then spend a budget it is not measuring, while a counter running fast fails safe.

2. A clippy error CI structurally could not see

cargo clippy -p jouleclaw-energy with no features fails -D warnings on vec_init_then_push at meter.rs:266.

CI's clippy step lints this crate as --features ioreport only. With any meter feature on, detect_meter has several pushes and the lint does not fire. With none, every hardware meter is cfg-ed out and the estimator's push is the only one left — so the default build is a different program, and a lint pass that never compiles it cannot speak for it.

The lint is right for that configuration and wrong as a rewrite: with features on, collapsing to vec![..] would be incorrect. So it is allowed at the function with the reason written down, rather than restructured to satisfy one cfg at the others' expense.

3. The blind spot itself

standards-build.yml now lints the default build of jouleclaw-energy beside the featured one, so this class cannot hide there again.

Same shape as check-tests-in-ci catching a test no job runs: a check that compiles one configuration says nothing about the others. Verified both ways — clippy exits 0 with and without ioreport, and 70 tests pass.

What is deliberately not touched

De-linking plausible_gpu_counter (a pub(crate) item, so not linkable from public docs) removes one of this crate's nine cargo doc warnings — the only one inside text this PR corrects.

The other eight stay. They link private or platform-gated items in process.rs, which is #[cfg(target_os = "macos")], and in rapl.rs — so which of them appear depends on the target. cargo doc is not part of this workspace's CI gate, and rewriting another author's docs across a cfg boundary from a host that sees only one side of it is how a fix becomes a regression on the other. They are reported here with the cause instead, so the next person gets the context rather than the surprise.

How the lint was actually found

Not by a sweep. I ran clippy without features while checking something else, and an echo in my own command masked the non-zero exit — so I nearly recorded it as clean. Worth writing down: cmd | grep ...; echo ok prints ok regardless, because the status belongs to the echo.

🤖 Generated with Claude Code

Three things in one crate, all found by reading `cargo doc` and `clippy` output that **no CI step reads**. ## 1. `CounterLiveness::Implausible` understated itself — my omission #341 made the GPU plausibility bound two-sided, so the variant is now produced for a counter that accrues far **less** than its board's telemetry says it drew, as well as for one running faster than the board can draw. Its doc comment still described only the fast direction. That is the defect family this crate keeps surfacing — documentation asserting something narrower than the code does — and here I introduced it. The doc now names both arms, and says which one matters at an energy ceiling: a counter reading low would otherwise be graded as hardware and then spend a budget it is not measuring, while a counter running fast fails safe. ## 2. A clippy error CI structurally could not see `cargo clippy -p jouleclaw-energy` with **no features** fails `-D warnings` on `vec_init_then_push` at `meter.rs:266`. CI's clippy step lints this crate as `--features ioreport` **only**. With any meter feature on, `detect_meter` has several pushes and the lint does not fire. With none, every hardware meter is `cfg`-ed out and the estimator's push is the only one left — so the default build is a *different program*, and a lint pass that never compiles it cannot speak for it. The lint is **right for that configuration and wrong as a rewrite**: with features on, collapsing to `vec![..]` would be incorrect. So it is allowed at the function with the reason written down, rather than restructured to satisfy one cfg at the others' expense. ## 3. The blind spot itself `standards-build.yml` now lints the **default** build of `jouleclaw-energy` beside the featured one, so this class cannot hide there again. Same shape as `check-tests-in-ci` catching a test no job runs: a check that compiles one configuration says nothing about the others. Verified both ways — clippy exits **0** with *and* without `ioreport`, and 70 tests pass. ## What is deliberately not touched De-linking `plausible_gpu_counter` (a `pub(crate)` item, so not linkable from public docs) removes one of this crate's **nine** `cargo doc` warnings — the only one inside text this PR corrects. The other eight stay. They link private or platform-gated items in `process.rs`, which is `#[cfg(target_os = "macos")]`, and in `rapl.rs` — so *which* of them appear depends on the target. `cargo doc` is not part of this workspace's CI gate, and rewriting another author's docs across a cfg boundary from a host that sees only one side of it is how a fix becomes a regression on the other. They are reported here with the cause instead, so the next person gets the context rather than the surprise. ## How the lint was actually found Not by a sweep. I ran `clippy` without features while checking something else, and an `echo` in my own command masked the non-zero exit — so I nearly recorded it as clean. Worth writing down: `cmd | grep ...; echo ok` prints `ok` regardless, because the status belongs to the `echo`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-10-20 04:09:13 -04:00

jouleclaw-energy: Implausible says what it now means, and a lint CI could not see ... 05f60d68dd

Three things, all in this crate, found by looking at `cargo doc` and clippy
output that no CI step reads.

**1. `CounterLiveness::Implausible` understated itself.** #341 made the GPU
plausibility bound two-sided, so the variant is produced for a counter that
accrues far *less* than its board's telemetry says it drew as well as for one
that runs faster than the board can draw. Its doc comment still described only
the fast direction — the enum's own documentation understating the variant,
which is the defect family this crate keeps surfacing, here introduced by my
own omission. The doc now names both arms and says which one matters at an
energy ceiling: a counter reading low would otherwise be graded as hardware and
then spend a budget it is not measuring, while a counter running fast fails
safe.

**2. A clippy error CI structurally could not see.** `cargo clippy -p
jouleclaw-energy` with **no features** fails `-D warnings` on
`vec_init_then_push` at `meter.rs:266`. CI's clippy step lints this crate as
`--features ioreport` only, and with any meter feature on there are several
pushes so the lint does not fire. The default build is a different program —
every hardware meter in `detect_meter` is behind a `cfg` — and a lint pass that
never compiles it cannot speak for it.

The lint is right for that configuration and wrong as a rewrite: with features
on, `vec![..]` would be wrong. So it is allowed at the function with the reason
written down, rather than restructured to satisfy one cfg at the others'
expense.

**3. The blind spot itself.** `standards-build.yml` now lints the default build
of `jouleclaw-energy` beside the featured one, so this class of error cannot
hide there again. This is the same shape as `check-tests-in-ci` catching a test
no job runs: a check that compiles one configuration says nothing about the
others.

Also de-links `plausible_gpu_counter` in the corrected comment, which is
`pub(crate)` and cannot be linked from a public item's docs — one of this
crate's nine `cargo doc` warnings, and the only one inside text being changed
here.

The remaining eight are **not** touched. They link private or platform-gated
items in `process.rs`, which is `#[cfg(target_os = "macos")]`, and in
`rapl.rs`, so which of them appear depends on the target. `cargo doc` is not in
this workspace's CI gate, and rewriting another author's docs across a cfg
boundary from a host that sees only one side is how a fix becomes a regression
on the other.

Verified: clippy clean with **and** without `ioreport`; 70 tests pass.

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

dcharlot merged commit c4bde05629 into main 2026-10-20 08:29:32 -04:00

dcharlot referenced this pull request from a commit 2026-10-20 08:29:34 -04:00

Merge pull request 'jouleclaw-energy: Implausible says what it now means, and a lint CI could not see' (#353) from fix/jouleclaw-energy-doc-links into main

dcharlot referenced this pull request 2026-10-20 13:51:58 -04:00

joule-code-conformance: the header undersold the harness by a whole suite #367

dcharlot referenced this pull request 2026-10-21 07:32:01 -04:00

jouleclaw-routing: ROUTING_JOULES is an Estimator-class floor, and says so #390

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!353

No description provided.