open-standards/mesh/README.md

# 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 ──▶ route (cheapest-sufficient) ──▶ authorise (JCP grant)
                                                     │
                                                     ▼
                     meter + debit ◀── serve (engine) ──▶ tokens
                                                     │
                                                     ▼
                         sealed JCR-1 receipt: µJ / accepted token
```

Four roles — **caller**, **router**, **engine**, **steward** — and four phases
per serve: route, authorise, meter, seal. The grant is decided by JCP's own
runtime before any work runs, so its expiry, caveats and remaining budget bind
here as at any JCP enforcement point, and the metered joules are debited
against it afterwards. A grant is spent only by its issuer, who signs each
presentation for one request, and only at the steward it was issued to; each
decision is journalled before the work, so a restart gives no budget back. 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`, and `ProcessMeter`: this process's own CPU and GPU energy for an engine that runs in process, measured when a span covers the whole request |
| `mesh-receipt` | the `mesh/1` receipt, JCR-1 sealing (det-CBOR + COSE_Sign1), and a hash-chained log |
| `mesh-core` | the orchestration that ties route → authorise → 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.