# 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)
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.