open-standards/sandbox/spec/receipts.md

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

Normative companion to 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.