jouleclaw: a routing plan carries the class of its energy figure #418

Merged

dcharlot merged 1 commit from fix/routing-plan-carries-its-class into main 2026-10-22 06:49:04 -04:00

Conversation 0 Commits 1 Files changed 10 +161 -2

2026-10-21

Transaction Science

jouleclaw: a routing plan carries the class of its energy figure ...

#390 said the enforceable fix for `router_joules` was to give `RoutingPlan` a
provenance, so a declared constant stops sharing a type with a measurement.
This is that change.

`RoutingPlan` gains `router_energy_class: Provenance`. Every router in this
workspace sets `Estimator`, because every one of them charges a constant or a
sum of constants — **nothing in routing is measured today**, and the type now
says so rather than leaving a reader to find out. It matters because the figure
is debited: `tier.rs` does `spent += plan.router_joules`, and a consumer that
cannot tell a measurement from a constant cannot tell whether the budget it is
enforcing means anything.

Three alternatives were rejected on the merits, not on taste:

- `JouleClass` is a tier taxonomy (Cache/Lawful/Embed/Model/Wire), not a grade.
- Moving `Provenance` into `jouleclaw-core` would be the tidier home, but it has
  **61 importers**; churning them to serve two crates is not proportionate.
- A local grade enum in cascade would make a third spelling of a vocabulary the
  family already has.

So cascade and routing depend on `jouleclaw-energy` with
`default-features = false`. Every hardware backend there is already opt-in, so
this adds no meter to the cascade's dependency graph — just the type.

**The magnitude is unchanged, deliberately.** `ROUTING_JOULES = 8e-9` J is
0.008 µJ: below the integer-microjoule unit the protocol uses (`EnergyReading`
is `u64` µJ, and "floating-point is forbidden in the protocol for
determinism"), so it rounds to zero there, and six orders of magnitude below
the ~1 mJ floor `jouleclaw-energy` itself calls realistic for an `Estimator`
source. The significand is unjustified. Correcting it needs a measurement;
substituting a different invented number would repeat the error this change
exists to label.

Falsification found two real gaps in my own tests before this was right:

- Mutating `LearnedRouter`'s and `PhasorRouter`'s own `RoutingPlan` literals
  changed **nothing**, because the test exercised `RoutingPlan::fallback` for
  both — their constructions were never reached. Fixed by driving each past
  cold start with `record_outcome` and asserting `!plan.is_fallback()` *first*,
  so the test cannot silently slide back onto the path that pins nothing.
- Mutating `PrivacyRouter`'s composition to take the inner plan's class was
  **invisible**, because with every shipped router on `Estimator` the two
  expressions agree. Separating them needed a stub inner router claiming
  `HwShunt`, which pins the actual rule: a sum containing an unmeasured
  constant is an estimate, however good the measured term was.

All four mutations now fail exactly one named test each.

Lockfiles: both workspaces that name these crates are refreshed
(`jouleclaw/jouleclaw-rs`, `joule-code/examples/l3-jouleclaw`); 47 lockfiles
current.

Verified: workspace check 0 errors, 486 test binaries green, 0 failures;
`l3-jouleclaw` check 0 errors. The 10 clippy findings in these crates are
pre-existing, unchanged in count, and all in lines this change did not author
(`coord_router_impl.rs:241` shifted to `:242` behind an inserted line); neither
crate is in CI's clippy list.

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

b6ad1b0763

• View at this point in history

2026-10-21 19:44:14 -04:00