mesh: say what the energy figure covers — the served span, not the request #385

Merged

dcharlot merged 1 commit from fix/mesh-energy-span-scope into main 2026-10-21 10:20:05 -04:00

Conversation 0 Commits 1 Files changed 3 +37 -2

2026-10-21

Transaction Science

mesh: say what the energy figure covers — the served span, not the request ...

`Mesh::serve` routes at step 1, authorises at step 2, and opens the meter
session at step 3, immediately before `engine.serve`. So a receipt's energy is
the served span and excludes routing and authorisation. Nothing said so:
`grep -niE "routing (is|energy)|excludes? rout|before routing"` over
`mesh/SPEC.md` and `mesh-core` found nothing, and the field was documented only
as "the honest, provenance-tagged energy span" — which span was never stated.

That omission matters in the direction this family has already decided is
dangerous. The grant is debited **this** figure and admits further work on the
strength of it, so a shortfall under-charges the ceiling —
**under-reporting is the unsafe direction at a ceiling**, the rule written into
`jouleclaw/SPEC.md` §1.3 and propagated across the meters in #354. For a
table-driven router the gap is negligible. For a router that itself runs a model
— a classifier or an LLM choosing the route — it is not, and a reader taking a
mesh receipt's energy as the energy of handling the request would be wrong by
exactly that inference.

SPEC §3.3 now states the boundary, forbids presenting the figure as the
request's energy, and says that an implementation metering a model-running
router should seal that span as its own field so a verifier can still separate
the two. `MeshReceipt::energy` and the step-3 comment in `mesh-core` say the
same thing where someone reading the code will meet it.

**This states the limit; it does not remove it.** Metering the routing span
means moving the session boundary, which changes every receipt's figure and has
conformance consequences — a scope decision, not a doc fix, and the digest item
(sweep 2026-10-19 #17) carries it as a wedge rather than a defect.

**No test pins the ordering, and the spec says so.** The meter is
snapshot-driven and routing takes no samples, so the boundary is an ordering
invariant in the serving path rather than an observable property of a receipt.
Putting the router behind a trait, as the engine already is, is what would let a
test pin it; `Mesh` holds `router: Router` concretely today while `meter` is
already `&dyn Meter`.

One citation trap avoided while writing this: `mesh/SPEC.md` has its own §5 and
no §1.3, so a bare "JCP SPEC §5" would read as mesh's §5 and "jouleclaw SPEC
§1.3" would dangle. `check-spec-refs` scans only `.rs` files, so neither would
have been caught. Both cross-standard references name their file.

Verified: `cargo check --workspace --all-targets --locked` 0 errors, 22 test
binaries green with 0 failures, clippy over `mesh-core`/`mesh-receipt` exits 0
with no finding in a mesh file, `cargo doc` clean, `check-spec-refs` 1693
citations across 16 standards all resolving.

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

3e1c6d4465

• View at this point in history

2026-10-21 05:42:26 -04:00