open-standards/sandbox/spec/receipts.md

# The energy receipt (per-device, JCR-1)

Normative companion to [`SPEC.md`](../SPEC.md) §6. RFC 2119 keywords apply.

A **receipt** accounts for the energy of one run, attributed to each device class the unit touched, two-part (`measured + estimated`) in integer microjoules, every reading honestly tagged, sealed in the family's JCR-1 envelope.

## Core

```
Receipt {
  unit_id  : ContentId,        // SPEC §3
  tier     : Tier,             // S0..S7
  devices  : [DeviceEnergy],   // one per used class; non-empty
  total    : { measured_uj : Option<u64>, estimated_uj : u64 },
  sequence : u64,
  nonce    : [u8; 8],
}

DeviceEnergy {
  class        : DeviceClass,  // Cpu | Simd | Gpu | Npu | Tpu | Lpu | Photonic | Quantum
  measured_uj  : Option<u64>,
  estimated_uj : u64,
  provenance   : Provenance,   // HwShunt | ModelBased | Estimator
}
```

## Per-device attribution (REQUIRED)

1. `devices` **MUST** contain exactly one record per device class the unit **actually used** during the run — not per granted class. A granted-but-unused class produces no record.
2. A host that ran accelerated work **MUST** emit a separate record for each accelerator class used. It **MUST NOT** fold accelerator energy into the `Cpu` record, and **MUST NOT** omit it.
3. `total.estimated_uj` **MUST** equal the sum of `estimated_uj` over `devices`. `total.measured_uj` is `Some(sum)` **only if** every record in `devices` has a `measured_uj`; otherwise it **MUST** be absent.

This is the clause that distinguishes a Sandbox receipt from a process-sandbox cost line: the joules are resolved to the silicon that spent them.

## Provenance discipline

| Tag | Meaning | `measured_uj` |
|---|---|---|
| `HwShunt` | read from a hardware energy interface for **this class** | **MUST** be present |
| `ModelBased` | from a calibrated per-operation model for this class | **MAY** be absent |
| `Estimator` | a coarse constant estimator | **MUST** be absent |

Per-class hardware interfaces the reference recognizes: **CPU** — Linux powercap/RAPL, AMD energy, Apple SMC; **GPU** — NVIDIA NVML `nvmlDeviceGetTotalEnergyConsumption`, AMD ROCm SMI, Intel Level Zero; **NPU/TPU/LPU/Photonic/Quantum** — the device's own energy or power-integration interface where one exists.

Rules:

- A host **MUST NOT** report a `measured_uj` it did not obtain from a hardware interface **for that specific class**. A GPU `measured` figure may never be inferred from a CPU shunt.
- The `(provenance, measured_uj)` coupling is enforced: `HwShunt` ⇒ present; `Estimator` ⇒ absent. A receipt violating the coupling is invalid (vector class **C3**).
- **At tiers S5 and above**, where a hardware interface for a used class exists on the host, the host **MUST** use it (`HwShunt`) rather than estimate. At lower tiers, where dedicated attribution may be unavailable, `ModelBased`/`Estimator` are permitted and the tag makes the limitation explicit.

## Reference estimators (non-normative)

When no hardware interface is available, a host estimates. The reference coefficients (microjoules) are tunable; the **standard is that the figure is reported and honestly tagged, not the constant**:

- CPU: per vCPU-millisecond cost from a calibrated table.
- Accelerator: per device-operation (e.g. per TFLOP-second, per inference forward pass) from a calibrated table, tagged `ModelBased`.
- Last resort: a coarse constant per class, tagged `Estimator`.

## Storage activity — measurement from contention (non-normative)

Storage is a resource the platform usually cannot meter: there is no per-tenant SSD energy interface the way there is RAPL for the CPU. The standard turns the **measurement technique behind a known side channel** to honest use. The contention a unit creates — random-read latency rising as a shared device saturates (`SECURITY.md` describes the adversarial version) — is, **measured cooperatively by the host and disclosed**, a real signal: a probe times page-cache-busting reads against an idle baseline and reports the device's observed activity (`iops`, `bytes`, `contention_ns`) and a model-based energy figure.

Two disciplines keep it honest:

1. **It is a distinct axis, not a device class.** Storage activity is its own line (`sandbox-meter::StorageActivity`); it does **not** enter the per-device-class energy sum of §6.2, and reporting it never perturbs the sealed receipt format or its vectors. Storage is not folded into a compute class it did not consume.
2. **It is never `HwShunt`.** A timing-derived figure is `ModelBased` (or coarser, `Estimator`); a timing channel is not a hardware shunt, and the provenance coupling (§6.3) is enforced for it exactly as for a device record. The same physics that leaks information when undisclosed becomes auditable telemetry when the host runs it on itself and tags it truthfully.

## Signed form (JCR-1)

The receipt seals as a **JCR-1 envelope** — the signed-receipt format shared across the family:

- a canonical **det-CBOR** signed core (RFC 8949 §4.2.1: length-first key order, no floats, no bools, no nulls — absent fields are dropped, not encoded as null),
- inside a **COSE_Sign1** envelope (RFC 9052), **EdDSA/Ed25519**, `alg = -8`,
- profile tag `"sandbox/1"` in the core, the steward identity in the COSE `kid`.

The `sandbox-meter` crate vendors the JCR-1 reference primitives so the library is self-contained, and is byte-compatible with the family's cross-language JCR-1 verifiers. A Sandbox receipt therefore verifies under existing JCR-1 tooling alongside Joule Code and JouleClaw receipts.

The receipt references, and is referenced by, the run's attestation: the attestation carries `receipt_id = content_address(receipt core)` (SPEC §7.1), binding the two without duplicating the energy figures.