check: no library source file is unreachable from its crate root #142

Merged

dcharlot merged 2 commits from sandbox/meter-delta-read into main 2026-10-13 06:37:24 -04:00

Conversation 0 Commits 2 Files changed 4 +250 -4

2026-10-10

David Charlot

jouleclaw-jcp: wire in two orphaned modules, and six tests that never ran ...

Rebasing the orphan-source guard over 817 commits of main found two new orphans
immediately, which is the clearest argument for the check that I could have
asked for. `jouleclaw-jcp/src/skill.rs` and `src/stack.rs` — 557 lines — are not
declared anywhere: `lib.rs` names only `mod tests`.

They were never abandoned, only never wired. Declaring them compiles clean, and
brings **six tests** alive that had never once executed:

    skill::a_failing_pressure_test_blocks_registration_with_failures_on_record
    skill::a_granted_skill_loads_after_passing_pressure
    skill::a_tampered_document_is_a_different_audience
    stack::a_tight_ceiling_keeps_cheap_queries_cheap
    stack::the_default_stack_answers_behind_a_grant
    stack::the_grant_is_the_budget_authority_across_walks

Those are not incidental. They assert that a tampered document resolves to a
different audience, that a grant is the budget authority across walks, and that
a failing pressure test blocks registration — tamper-detection and
grant-authority properties, written down, compiled never, run never. All 15
tests in the crate now pass.

Baselining them would have been the wrong move and is worth saying why: the
guard exists to stop growth, so pinning code that arrived *after* the baseline
would have converted it from a ratchet into a record of defeat. The baseline
stays at the original 25, all in `jouleclaw-omni`, which are a different
question — 20k lines whose disposal is the owner's call, not a two-line `mod`
declaration.

Also in this commit, from the original change: the orphan check itself, its CI
job with a self-test that fails closed, and a corrected header on
`jouleclaw-omni/runtime/energy.rs`, which documented itself as measuring energy
via IOReport while multiplying `getrusage` CPU seconds by a fixed 15 W and
apportioning the result 60/20/20 across subsystems.

Re-verified on today's main after the rebase: the self-test still fails closed
with a planted orphan and passes without one, exit codes checked without a pipe,
and the ratchet reports the pinned 25 unchanged.

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

0c0b66f001

• View at this point in history

2026-10-10 09:54:53 -04:00

David Charlot

check: no library source file is unreachable from its crate root ...

Going after the meters turned up a worse instance of a family this repo keeps
finding. `jouleclaw-omni/src/runtime/energy.rs` documents itself as measuring
"actual GPU, CPU, ANE and DRAM energy consumption in joules using Apple's
IOReport framework". It does not call IOReport. The macOS path multiplies
`getrusage` CPU seconds by a fixed 15 W; the other path multiplies wall-clock by
45 W; each then splits the result 60/20/20 across subsystems by constant
fractions. It has **zero tests**, and `runtime/mod.rs` does not declare it — so
it has never been compiled, by anything, ever.

That is the strongest member of the family. A feature-gated test with no
`--features` reports zero tests; a platform-gated meter on a single-platform
runner compiles out; a conformance suite in `main()` gets built and never run.
An orphan source file does not even type-check. It is invisible to cargo check,
cargo test, clippy and every conformance suite simultaneously, and it cannot
fail because nothing asks it anything.

The hazard is the next reader, not the dead code. A real meter with a per-rail
liveness gate already lives in the same workspace (`jouleclaw-energy`); someone
who trusts this file's header and wires it in instead gets CPU-seconds times a
guess, apportioned by invented fractions — energy derived from a performance
proxy, which is the thing the whole metering ladder exists to grade against.

So: `scripts/check-orphan-sources.py`, wired into the hygiene workflow. The
per-subsystem split is worth naming separately — four fields reading as four
independent observations when all four are fractions of one number is precision
standing in for measurement, and it invites conclusions nothing here supports.

**Measured, not estimated.** 1659 library sources checked; 25 orphans, all in
`jouleclaw-omni`, 19,964 lines never compiled. Every other crate is clean.
My first pass said 77 — it counted `src/bin/*.rs`, which cargo auto-discovers,
so the exclusions are part of the check rather than a convenience. The baseline
was then generated by the detector instead of retyped, because hand-copying it
pinned 15 of 25 and the check caught the other ten.

Falsified in both directions before being trusted, and the CI step repeats the
self-test on every run: a planted orphan must fail the check, and removing it
must pass. Exit codes verified without a pipe — `$?` after `| head` is head's
status, which is how a gate silently stops gating.

The baseline pins today's 25 so this does not go red on a pre-existing
condition, and names what the file falsely claims. Removing an entry is the
point; adding one is a regression to argue for in a commit message.

`energy.rs` itself gets a corrected header and nothing else. I had added a
declared `EnergyBasis` to it and reverted that: the field made the orphan stop
compiling, and a broken orphan is worse than an honest one. Whether those 25
files are wired up or deleted is not mine to decide — 20k lines is someone's
work, and the guard stops the problem growing either way.

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

104a8b444c

• View at this point in history

2026-10-10 09:51:01 -04:00