Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 15 Packages Wiki Activity Actions

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
dcharlot commented 2026-10-21 05:42:45 -04:00
Owner
Copy link

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.

Why the omission matters in this particular direction

The grant is debited this figure and admits further work on the strength of it. So a shortfall under-charges the ceiling — and 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.

What this changes

  • SPEC §3.3 states the boundary, forbids presenting the figure as the request's energy, and says an implementation that meters 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 where someone reading the code will meet it.

What it does not change — stated plainly

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. That is a scope decision rather than a doc fix, and the sweep item it comes from (2026-10-19 #17) carries it as a wedge, not a defect.

No test pins the ordering, and the spec now 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. Mesh holds router: Router concretely while meter is already &dyn Meter — putting the router behind a trait, as the engine already is, is what would let a test pin it. I would rather name that than imply coverage I did not add.

A citation trap worth recording

mesh/SPEC.md has its own §5 ("The serving engine") and no §1.3. So a bare "JCP SPEC §5" would read as mesh's §5, and "jouleclaw SPEC §1.3" would dangle — and check-spec-refs scans only .rs files, so neither would have been caught. Both cross-standard references name their file instead. (This is the same trap that failed one of my earlier PRs when it was in a .rs file, where the guard does look.)

Verification

  • cargo check --workspace --all-targets --locked (mesh-rs) — 0 errors
  • cargo test --workspace --locked — 22 test binaries green, 0 failures
  • cargo clippy -p mesh-core -p mesh-receipt --all-targets --no-deps --locked -- -D warnings — exits 0, with 0 findings in a mesh file (the 44 it prints are all in jouleclaw-backend-apple, a macOS-only Metal path dep that --no-deps does not suppress across workspaces; mesh is not in CI's clippy list at all)
  • cargo doc --no-deps -p mesh-receipt — clean
  • check-spec-refs — 1693 citations across 16 standards, all resolve; check-comparative-prose clean

🤖 Generated with Claude Code

`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. ## Why the omission matters in this particular direction The grant is debited **this** figure and admits further work on the strength of it. So a shortfall under-charges the ceiling — and **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. ## What this changes - **SPEC §3.3** states the boundary, forbids presenting the figure as the request's energy, and says an implementation that meters 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 where someone reading the code will meet it. ## What it does not change — stated plainly **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. That is a scope decision rather than a doc fix, and the sweep item it comes from (2026-10-19 #17) carries it as a wedge, not a defect. **No test pins the ordering, and the spec now 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. `Mesh` holds `router: Router` concretely while `meter` is already `&dyn Meter` — putting the router behind a trait, as the engine already is, is what would let a test pin it. I would rather name that than imply coverage I did not add. ## A citation trap worth recording `mesh/SPEC.md` has its own **§5** ("The serving engine") and **no §1.3**. So a bare "JCP SPEC §5" would read as *mesh's* §5, and "jouleclaw SPEC §1.3" would dangle — and `check-spec-refs` scans only `.rs` files, so neither would have been caught. Both cross-standard references name their file instead. (This is the same trap that failed one of my earlier PRs when it was in a `.rs` file, where the guard *does* look.) ## Verification - `cargo check --workspace --all-targets --locked` (`mesh-rs`) — **0** errors - `cargo test --workspace --locked` — **22** test binaries green, **0** failures - `cargo clippy -p mesh-core -p mesh-receipt --all-targets --no-deps --locked -- -D warnings` — exits **0**, with **0** findings in a mesh file (the 44 it prints are all in `jouleclaw-backend-apple`, a macOS-only Metal path dep that `--no-deps` does not suppress across workspaces; mesh is not in CI's clippy list at all) - `cargo doc --no-deps -p mesh-receipt` — clean - `check-spec-refs` — 1693 citations across 16 standards, all resolve; `check-comparative-prose` clean 🤖 Generated with [Claude Code](https://claude.com/claude-code)
mesh: say what the energy figure covers — the served span, not the request
All checks were successful
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 12s
Details
standards workspaces build + test / macOS energy backends (pull_request) Has been skipped
Details
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 1m42s
Details
standards workspaces build + test / joulehook-rs (joulehook/joulehook-rs, joulehook-rs, linux) (pull_request) Successful in 1m13s
Details
standards workspaces build + test / mesh-rs (mesh/mesh-rs, -p mesh-engine-gguf -p mesh-openai --features mesh-engine-gguf/gguf,mesh-openai/server, mesh-rs, linux-arm64) (pull_request) Successful in 2m23s
Details
3e1c6d4465 
`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]>
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
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!385
No description provided.