33f0b89124
The owner's decision, applied: a vendor energy counter (RAPL, NVML, IOReport) is a real reading, and what separates one such reading from another is provenance, not accuracy. This crate gave RAPL and NVML `HwShunt` and gave the IOReport counter `ModelBased`, on the reasoning that Apple's Energy Model is a vendor model. That reasoning grades accuracy. What the counter could not establish was provenance: on macOS 27.0.1 its CPU rails are frozen for an unprivileged reader, and that is now caught by the liveness probe. A counter that has passed it is as much a reading as RAPL is. The grade. `AppleIoReportCounter` declares `HwShunt`, and stamps it on every reading through one constant, `READING_GRADE`, shared by `provenance()` and `read()`. It earns the grade by being live: the counter exists to read only where `admits()` let it through (CPU rail `Live`), and a declined counter produces no reading to carry any grade, so a frozen host still meters through the load-average estimator at `Estimator`. The rule, written once and shared (jouleclaw SPEC §1.3, §9.4; JCR-1 §2.3; the crate docs; vendor-energy PROTOCOL/README): a vendor counter's reading MAY be graded as a hardware reading only while the counter is demonstrably live for the domain the figure claims; the implementation MUST have observed the counter covering that domain advance under load (for IOReport: the CPU rail itself, in at least 5 intervals, 4 of every 5, over at least 300 ms while the probing thread burns CPU). A counter present but not live MUST NOT produce a hardware-graded figure; the implementation falls back to its estimator or reports the work unmetered, and SHOULD record why. A figure MUST NOT claim coverage of a domain its counter does not read; where the format has a coverage field, such a figure is Partial. No partial reading from the GPU rail. Where the CPU rail is frozen but `GPU Energy` still advances (the M5 Max), the counter stays declined. The GPU rail is machine-wide: every GPU client on the host moves it, display compositing included, with nothing of the metered work running. It does not cover part of the work; it covers other work, so no coverage field makes it honest. The rationale is in the module docs and SPEC §1.3. Docs and data that said otherwise: - SPEC §1.3 table and floors, §9.4; JCR-1 §2.3 and the crate README (toy vectors become measurements only off counters that were live). - JCR-1 vector 6's description said "measured on Apple IOReport". Its joules are toy values like every vector's. Only the `description` changed; it sits outside the signed core, which `verify.py` builds from `receipt` alone. Both verifiers pass 10/10 after the edit: `verify.py` (cbor2 6.1.4, cryptography 50.0.2, exit 0) and the independent `verify.go` (exit 0). `git diff` of the file is that one line; a field-by-field JSON diff finds only (6, description). The conformance README's slot 6 line follows. - vendor-energy conformance: README row 27 names `AppleIoReportCounter` and the `HwShunt` grade, with the liveness condition a filled fixture must meet; `apple-silicon-ioreport.json` is an unsigned, empty stub (`signed_by` null, every workload not run, no hash of it anywhere), so its `impl` and `provenance` are corrected in place. - MEASURED_ENERGY.md: a dated note that the 74.1 J / 25.5 W row was committed 2026-06-12, predates macOS 27, and recorded neither chip nor OS. The "reads CPU/GPU/ANE/DRAM with no sudo" claim is replaced by what macOS 27.0.1 does: the counter opens without sudo, but the CPU rails are frozen (all 645 rails on the M3 Ultra), so those hosts are estimated. - local-index / rerank tier SHOULDs, the CLI's `meter` help, meter.rs, apple.rs, energy_probe, Cargo feature comments, harness-econ docs. - l3-jouleclaw README: it claimed `HwShunt` on RAPL/NVML hosts, but the binding builds jouleclaw-energy with `ioreport` only, so off Apple Silicon the receipt is the token estimate. It now says what happens on each host. - mesh-schema's `HwShunt` definition includes vendor counters subject to liveness; mesh-meter, the mesh README and mesh-engine-gguf no longer say real silicon alone yields `HwShunt`. - The Live-branch assertions in mesh-meter, l3-jouleclaw and jouledesk-github expected `ModelBased` for IOReport; they expect `HwShunt`. jouledesk-github's fixtures that paired `apple-ioreport` with `ModelBased` now pair it with `HwShunt`, and keep a `ModelBased` case under a neutral meter name. Tests. `a_live_counters_readings_are_graded_as_hardware_readings` builds a counter on `Live` directly. That opens the real all-channel subscription, which opens here even though the gate declines this host. It reads it twice and asserts each reading is `HwShunt` over `SocTotal`. On this M5 Max (macOS 27.0.1): "an admitted IOReport counter: opens=true, 2 readings, each graded HwShunt", so the read path is covered on a frozen host. With `--features "ioreport rapl"`, `a_live_ioreport_reading_has_the_grade_of_a_rapl_reading` compares the grade with `RaplCounter`'s own. The used/declined tests assert `HwShunt` in their live branch. This host still takes the declined branch: "ioreport declined (CpuRailFrozen): 154 ms of CPU work metered by `apple-silicon` as 6200000 µJ, provenance estimator". Run on this M5 Max: jouleclaw-energy 24+1+1 (default), 76 lib + 1 + 1 (`ioreport`), 79 lib (`ioreport rapl`); jouleclaw-jcr1 50; harness-econ 14; local-index 41; rerank 37; cli 10; mesh-meter (`hw-meter-apple`) 10; mesh-engine-gguf 1; l3-jouleclaw 2 + 4 (2 ignored, need a model); jouledesk-github 12. All pass. Falsified, each mutant restored with `git checkout` and the tree confirmed clean: - `READING_GRADE` set back to `ModelBased`: the new test fails at the declared grade (left: ModelBased, right: HwShunt), 75 passed / 1 failed. - Only `read()`'s stamp set back to `ModelBased` (the declared grade left at `HwShunt`): the new test fails on the reading itself, "a live counter's reading is not graded as a hardware reading" (ModelBased, SocTotal) vs (HwShunt, SocTotal), 75 / 1. The read path is what the test pins. Co-Authored-By: Claude Opus 5.5 <[email protected]>
101 lines
4.9 KiB
Markdown
101 lines
4.9 KiB
Markdown
# Mesh
|
|
|
|
**Energy-accounted inference serving & routing.** One of the
|
|
[Transaction Science open standards](../README.md).
|
|
|
|
Mesh treats every inference as a metered transaction. A request declares a
|
|
**joule ceiling** and a **fidelity floor**; the mesh routes it to the
|
|
cheapest-sufficient model on the cheapest-sufficient backend, serves it under an
|
|
energy meter, and seals a receipt whose headline figure is **microjoules per
|
|
accepted output token** — measured at the meter, not estimated from a price list.
|
|
|
|
The serving shelf reports dollars per token and tokens per second. Mesh reports
|
|
the number that is physical, comparable across hardware, and impossible to
|
|
inflate: the joule.
|
|
|
|
- **Spec:** [`SPEC.md`](SPEC.md) (CC-BY-4.0)
|
|
- **Reference code:** [`mesh-rs/`](mesh-rs/) (Apache-2.0)
|
|
- **Conformance vectors:** [`conformance/v1/`](conformance/v1/)
|
|
|
|
## The shape
|
|
|
|
```
|
|
ServeRequest ──▶ authorise (JCP grant) ──▶ route (cheapest-sufficient)
|
|
│
|
|
▼
|
|
meter ◀── serve (engine) ──▶ tokens
|
|
│
|
|
▼
|
|
sealed JCR-1 receipt: µJ / accepted token
|
|
```
|
|
|
|
Four roles — **caller**, **router**, **engine**, **steward** — and four phases
|
|
per serve: authorise, route, meter, seal. See [`SPEC.md`](SPEC.md) §2.
|
|
|
|
## The reference workspace
|
|
|
|
`mesh-rs/` is a pure-Rust reference implementation:
|
|
|
|
| Crate | What it is |
|
|
|---|---|
|
|
| `mesh-schema` | wire types — `ServeRequest`, `Fidelity`, two-part `Energy`, `RouteDecision`, `ServeOutcome` |
|
|
| `mesh-router` | energy-weighted cheapest-sufficient routing with a full candidate audit |
|
|
| `mesh-engine` | the `ServingEngine` interface + a deterministic, weights-free `ReferenceEngine` |
|
|
| `mesh-engine-gguf` | a **real** backend (behind `gguf`): wraps the family's pure-Rust GGUF/Metal inference substrate so the mesh routes and meters actual model tokens |
|
|
| `mesh-meter` | the meter window; an always-available estimator + an optional bridge to the family hardware meter (RAPL / NVML / Apple) behind `hw-meter` |
|
|
| `mesh-receipt` | the `mesh/1` receipt, JCR-1 sealing (det-CBOR + COSE_Sign1), and a hash-chained log |
|
|
| `mesh-core` | the orchestration that ties authorise → route → meter → seal together |
|
|
| `mesh-conformance` | the deterministic reference scenario, its checks, and the `gen-vectors` bin |
|
|
|
|
Mesh **rides on** [JCP](../jcp/) (a serve request is authorised by a JCP grant;
|
|
receipts seal in JCR-1), **dispatches to** runtimes such as
|
|
[JouleClaw](../jouleclaw/), and **routes across** compute described by
|
|
[EOC](../eoc/) and isolated by [Sandbox](../sandbox/). It introduces no new
|
|
cryptography (see [`SPEC.md`](SPEC.md) §9).
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
cd mesh-rs
|
|
|
|
# all crates green
|
|
cargo test --workspace
|
|
cargo clippy --workspace --all-targets
|
|
|
|
# end-to-end: mint a JCP grant, serve, print the sealed receipt
|
|
cargo run -p mesh-core --example demo
|
|
|
|
# on Linux/RAPL or a CUDA/NVML box, meter real silicon (HwShunt provenance, where
|
|
# the counter is live; a counter that is not live falls back to the estimator)
|
|
cargo run -p mesh-core --example demo --features hw-meter-rapl
|
|
|
|
# regenerate the published conformance vectors
|
|
cargo run -p mesh-conformance --bin gen-vectors -- ../conformance/v1
|
|
|
|
# serve a REAL model end-to-end through Mesh (Falcon-H1 0.5B), seal the receipt
|
|
cargo run --release -p mesh-engine-gguf --features gguf --bin serve_falcon -- \
|
|
/path/to/falcon-h1-0.5b-instruct 12 "The capital of France is"
|
|
```
|
|
|
|
The `serve_falcon` run demonstrates the **whole standard** on real model tokens:
|
|
a JCP grant authorises each request (an underfunded grant is refused *before any
|
|
decode runs*), the cheapest-sufficient backend is chosen, the decode is metered,
|
|
and a `mesh/1` receipt is sealed and hash-chained across the session — e.g.
|
|
prompt *"The capital of France is"* → `" Paris. It is known for its historical
|
|
landmarks"`, prompt *"Photosynthesis is the process by which"* → `" plants
|
|
convert sunlight into chemical energy in the form of"`, with both seals verifying
|
|
and the chain's prev-links intact.
|
|
|
|
The demo prints the route (every backend weighed, with the reason each was kept
|
|
or rejected), the honest energy provenance, and the wedge metric — then verifies
|
|
the sealed envelope under the steward key.
|
|
|
|
## Status
|
|
|
|
v0.1.0-draft.1. Reference workspace builds and tests green (`mesh-schema`,
|
|
`mesh-router`, `mesh-engine`, `mesh-meter`, `mesh-receipt`, `mesh-core`,
|
|
`mesh-conformance`); `cargo clippy --all-targets` warning-free; published vectors
|
|
in [`conformance/v1/`](conformance/v1/). The reference engine is deterministic and
|
|
weights-free; production backends implement the same `ServingEngine` interface —
|
|
`mesh-engine-gguf` (behind `gguf`) is a real one over the family's pure-Rust
|
|
GGUF/Metal substrate, kept out of the default build so it needs no weights.
|