open-standards/mesh/SPEC.md

# Mesh — Energy-Accounted Inference Serving & Routing

**Version:** 0.1.0-draft.1 · **Status:** Draft · **Profile:** `mesh/1`
**Specification text:** CC-BY-4.0 · **Reference code (`mesh-rs/`):** Apache-2.0

Mesh is the open standard for **serving and routing 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.

Mesh is one of the [Transaction Science open standards](../README.md).
Transaction Science is the steward, not the proprietor: the wire format and the
right to fork are public.

---

## §1 Why Mesh exists

The serving shelf reports two numbers: dollars per token and tokens per second.
Neither tells an operator, an auditor, or a regulator what an inference **cost**
— in the one unit that is physical, comparable across hardware, and impossible to
inflate: the joule. Mesh makes that number first-class. Every served inference
produces a signed receipt carrying the route that was taken and *why*, the recipe
that served it, the honest provenance of the energy figure, and the joules per
accepted token.

Mesh does not replace the runtime that executes one inference, nor the substrate
that supplies the compute. It is the **front door** in front of many models and
many backends: the layer that decides where a request goes, meters what it spent,
and proves it (§9).

---

## §2 Roles and the serve lifecycle

A Mesh deployment has four roles:

- **Caller** — issues a `ServeRequest` and, optionally, the JCP grant that
  authorises it.
- **Router** — selects a backend (§4).
- **Engine** — a backend that serves the request (§5).
- **Steward** — the endpoint that meters the span (§5/§6) and seals the receipt
  (§6). The steward identity is the COSE `kid` and signs the receipt log.

One serve proceeds in four phases, in order:

1. **Authorise.** If the request rides on a JCP `SignedGrant`, the steward MUST
   verify the issuer signature, confirm the capability permits the action
   `infer` on the request's content id, and confirm the grant's joule budget is
   ≥ the request's joule ceiling. A failure at any step aborts the serve before
   any work is done.
2. **Route.** The router selects the cheapest admissible backend (§4). If none is
   admissible, the serve fails with the router's recorded reason.
3. **Meter.** The steward opens an energy window, calls the engine, and closes
   the window. Energy MUST be metered **around** the engine; an engine MUST NOT
   self-report energy.
4. **Seal.** The steward builds the receipt (§6), stamps it into its hash-chained
   log, and seals it as a JCR-1 envelope.

---

## §3 The request and the energy record

### §3.1 `ServeRequest`

A request is content-addressed. Its identity `request_id = ContentId.of(request)`
is the resource a JCP capability authorises and the `request_id` on the receipt.

| Field | Type | Meaning |
|---|---|---|
| `prompt_hash` | ContentId (BLAKE3) | content address of the prompt bytes — never the prompt text |
| `prompt_tokens` | u32 | declared input token count (for the estimate) |
| `max_tokens` | u32 | output token ceiling |
| `fidelity_floor` | Fidelity | minimum acceptable fidelity (§3.2) |
| `joule_ceiling_uj` | u64 | hard energy budget, microjoules |

A conforming request MUST carry both a `fidelity_floor` and a `joule_ceiling_uj`.
The pair is the contract: *give me an answer at least this good, for at most this
much energy.*

### §3.2 Fidelity

Fidelity is an ordered scale `F0 … F4` — `F0` the coarsest sufficient answer
(cache / lawful / tiny model), `F4` a frontier-grade response. Ordering is
normative: a backend is admissible only when its level ≥ the request's floor
(§4).

### §3.3 Energy and provenance

Energy is a two-part integer-microjoule record with an honest provenance tag:

```
Energy { measured_uj: Option<u64>, estimated_uj: u64, provenance: Provenance }
Provenance ∈ { HwShunt, ModelBased, Estimator }
```

The coupling is normative and MUST be enforced before a receipt is sealed:

- `HwShunt` ⇒ `measured_uj` is present (a hardware reading exists).
- `Estimator` ⇒ `measured_uj` is absent (no measurement is implied).
- `ModelBased` ⇒ `measured_uj` MAY be absent.

A receipt that violates the coupling MUST NOT be sealable. This is the rule that
keeps "measured" honest: a deployment with no hardware meter reports `Estimator`
and says so, rather than dressing an estimate up as a measurement.

---

## §4 Routing — cheapest-sufficient

For each registered backend the router computes an estimate
`est_total_uj = uj_per_token × (prompt_tokens + max_tokens)` and marks it
**admissible** iff:

```
backend.fidelity ≥ request.fidelity_floor   AND   est_total_uj ≤ request.joule_ceiling_uj
```

The router MUST choose the admissible backend with the **lowest** `est_total_uj`.
Ties are broken deterministically (registration order). When no backend is
admissible the serve fails, and the decision records why.

The router MUST record, for every backend it weighed, a `RouteCandidate` with its
fidelity, estimate, admissibility, and — when inadmissible — a human-readable
reason (below floor / over ceiling). The chosen route MUST carry a one-line
justification. This is what makes a route **auditable from the receipt alone**:
the cheapest sufficient answer is preferred and a frontier model is the expensive
last resort, and the comparison is denominated in joules.

A model is addressed as a **recipe** — a base plus optional merges/adapters — not
a fixed blob, so the receipt can record *which* composed model answered.

---

## §5 The serving engine

A backend implements one interface: advertise a fidelity level and a modeled
per-token energy cost, and serve a request producing tokens and a `ServeOutcome`:

```
ServeOutcome {
  tokens_in, tokens_out, tokens_accepted,
  cache_hit_tokens, spec_proposed, spec_accepted
}
```

The input token payload travels **with** the serve call, alongside the request —
it is never part of the request's sealed identity and never enters the receipt,
which records only the content-addressed `prompt_hash` (§3.1). A receipt is
therefore safe to publish without disclosing the prompt.

`tokens_accepted` is the denominator of the wedge metric. For greedy decode it
equals `tokens_out`; under speculative decoding it is the number of proposed
tokens the target model accepted. `cache_hit_tokens` records output served from a
prefix/result cache (energy saved). An engine MUST do real work proportional to
the tokens it serves so the surrounding meter reads a real span; it MUST NOT
self-report energy.

The reference engine (`mesh-engine::ReferenceEngine`) is deterministic and
weights-free, for conformance. Production backends — a quantized device-resident
decoder, a high-throughput batching server — implement the same interface and
drop in unchanged; `mesh-engine-gguf::GgufEngine` (behind the `gguf` feature) is
one such backend over a pure-Rust GGUF/Metal decoder, so the mesh routes and
meters real model tokens.

---

## §6 The receipt — `mesh/1`

A `MeshReceipt` is sealed with **JCR-1**: canonical det-CBOR (RFC 8949 §4.2.1)
inside a COSE_Sign1 envelope (RFC 9052, EdDSA/Ed25519, `alg = -8`), byte-compatible
with the rest of the family's receipts. The signed core forbids floats, booleans,
and nulls; booleans are encoded as `0|1` uints and absent options dropped.

### §6.1 Wire fields (`mesh/1`)

| Key | Meaning |
|---|---|
| `mesh_receipt` | `"mesh/1"` |
| `request_id` | hex content id of the request |
| `grant_id` | hex JCP grant id this inference debited (omitted if ungranted) |
| `backend`, `recipe` | the backend and composed model that served it |
| `route` | the router's one-line justification |
| `tokens_in/out/accepted`, `cache_hit_tokens`, `spec_proposed/accepted` | the outcome counters |
| `fidelity_floor` | the floor the request demanded (uint) |
| `fidelity_met` | `0|1` — did the served backend meet the floor |
| `estimated_uj` | always present |
| `measured_uj` | present **iff** provenance is `HwShunt` |
| `uj_per_accepted_token` | **the wedge metric** — `energy.uj() / tokens_accepted` |
| `energy_provenance` | `HwShunt | ModelBased | Estimator` |
| `sequence`, `prev` | hash-chain position and prior envelope's content id |
| `nonce`, `steward` | per-receipt nonce and the sealing identity (COSE `kid`) |

### §6.2 The wedge metric

`uj_per_accepted_token = energy.uj() / tokens_accepted`, where `energy.uj()` is
the measured figure if present, else the estimate. It is `null`/absent when no
tokens were accepted. This is the number Mesh exists to make legible, and it is
sealed into every receipt.

### §6.3 Hash chain

A steward keeps a receipt log. Appending a receipt stamps its `sequence` (from 0)
and `prev` (the content id of the previous sealed envelope; absent at genesis),
seals it, and advances the head. The log is tamper-evident end to end: altering
any envelope breaks verification of that receipt and the chain link from the next.

---

## §7 Conformance

A conforming implementation MUST:

1. Reject a serve whose grant fails verification, does not permit `infer` on the
   request, or carries a budget below the request's joule ceiling (§2.1).
2. Choose the cheapest admissible backend and record every candidate weighed
   (§4).
3. Meter energy around the engine and tag provenance honestly, enforcing the
   `Energy` coupling before sealing (§3.3).
4. Seal the receipt as a JCR-1 `mesh/1` envelope and compute
   `uj_per_accepted_token` (§6).
5. Maintain a tamper-evident hash chain (§6.3).

The published vectors in [`../conformance/v1/`](../conformance/v1/) pin a
deterministic reference serve. `reference/signed_core.hex` MUST canonical-CBOR
encode identically across implementations, and `reference/envelope.hex` MUST be
reproducible from it with the steward key in `meta.json`. Regenerate with:

```text
cargo run -p mesh-conformance --bin gen-vectors -- ../conformance/v1
```

---

## §8 Security considerations

Mesh composes proven primitives: Ed25519 signatures, BLAKE3 content addressing,
RFC 9052 COSE_Sign1, and the JCP capability model. It introduces no new
cryptography. Two properties are correctness, not style:

- **Authorisation happens outside the model.** The grant check (§2.1) is enforced
  by the steward before any inference runs; a prompt cannot grant itself budget
  or capability.
- **Honesty is enforced at seal time.** A receipt cannot claim a measurement it
  does not have (§3.3). An operator without a hardware meter produces honest
  `Estimator` receipts.

Energy figures are only as honest as the worst meter in the span. A receipt's
provenance tag states which meter produced its figure; consumers SHOULD treat
`Estimator` figures as bounds, not measurements.

---

## §9 Relationship to the family

Mesh is the serving + routing fabric. It is expressed in primitives the family
already publishes, and it composes with the neighbouring standards rather than
duplicating them:

- It **rides on [JCP](../jcp/)**: a serve request is authorised by a JCP `Grant`
  (capability ⊗ joule-budget), and the receipt seals in JCR-1 — the same envelope
  every family receipt uses.
- It **dispatches to runtimes** such as [JouleClaw](../jouleclaw/): a backend that
  executes one inference cheaply is one engine behind the mesh.
- It **routes across compute** described by [EOC](../eoc/) and isolated by
  [Sandbox](../sandbox/): a backend may be a metered, attested execution target.

The boundary is deliberate: a runtime executes *one* inference; Mesh routes
across *many* models and *many* backends and proves what each one cost.