# Joule Code — The Receipt

Normative sub-specification of [`../SPEC.md`](../SPEC.md) §6. CC-BY-4.0.

Every coding operation carries a **receipt**: a signed, two-part energy record carried in a Joule Wire Protocol (JWP) frame. The receipt is the falsifiable cost basis of the operation — not its market price, but its honest energy cost.

## 1. Structure

```
Receipt {
  op_id:      ContentId,
  tier:       Tier,
  energy:     Energy,
  sequence:   u64,
  nonce:      [u8; 8],
  sig:        [u8; 64],   // Ed25519 over the energy preimage (§3)
}

Energy {
  measured_uj:  Option<u64>,   // present ONLY when from a live hardware interface (§2)
  estimated_uj: u64,           // always present
  provenance:   Provenance,
}

Provenance = HwShunt | ModelBased | Estimator
```

## 2. The provenance contract (REQUIRED)

The `Provenance` tag states how honest the figure is, and the spec never claims more than the platform delivers:

- `HwShunt` — read from a hardware energy interface: an external shunt, or a vendor energy counter (RAPL, NVML, Apple SMC/IOReport) while that counter is live for the domain the figure claims (below). A reading tagged `HwShunt` **MUST** have `measured_uj = Some`.
- `ModelBased` — computed from a calibrated per-operation energy model. `measured_uj` **MAY** be absent.
- `Estimator` — a coarse constant estimator (e.g. per-token coefficients applied to L4 token counts). `measured_uj` **MUST** be absent.

A runtime **MUST NOT** populate `measured_uj` from anything but a hardware interface, and **MUST NOT** tag a reading `HwShunt` without a present `measured_uj`. Absence is the honest answer when the platform cannot measure.

**Vendor counters.** A reading from a vendor energy counter (RAPL, NVML, Apple IOReport, ...) **MAY** be graded as a hardware reading only while the counter is demonstrably live for the domain the figure claims: the implementation **MUST** have observed the counter covering that domain advance under load (for Apple IOReport: the CPU energy rail itself advancing in at least 5 sample intervals, in at least 4 of every 5, over at least 300 ms while the probing thread burns CPU; an interval runs from when one sample is in hand to when the next is, and only one no longer than three of the probe's ticks, 75 ms at its 25 ms tick, counts: a longer one counts as nothing, neither among the intervals, nor as an advance, nor towards the 300 ms, which is the summed length of the intervals that count). A counter that is present but not live — frozen, or republished in lumps — **MUST NOT** produce a hardware-graded figure; the implementation falls back to its estimator or reports the work unmetered, and **SHOULD** record why. A figure **MUST NOT** claim coverage of a domain its counter does not read; where the format has a coverage field, such a figure is Partial.

In this receipt the hardware grade is a present `measured_uj` and the `HwShunt` tag: a counter that is present but not live supplies neither.

## 3. Signed form — JCR-1 (v0.2)

As of v0.2 the receipt's signed form is a **JCR-1 envelope** (SPEC §6.1), the signed-receipt format shared across the Transaction Science family — not a bespoke preimage. A Joule Code receipt therefore verifies under the family's existing JCR-1 tooling and its cross-language (Python/Go) reference verifiers.

```
core      = canonical-det-CBOR(           # RFC 8949 §4.2.1, length-first keys
              { jc_receipt: "joule-code/1", op_id, tier, estimated_uj,
                measured_uj?, energy_provenance, sequence, nonce, steward } )
envelope  = COSE_Sign1(                    # RFC 9052, EdDSA -8
              protected = { 1: -8, 4: bstr(steward) },
              payload   = core,
              signature = Ed25519_sign(endpoint_secret, Sig_structure) )
```

`Sig_structure` is `["Signature1", protected, external_aad(empty), core]` (RFC 9052 §4.4). Verification parses the tagged COSE_Sign1 (CBOR tag 18), rejects any `alg` but `-8`, rejects a `kid` other than the expected steward, checks the Ed25519 signature, and confirms the payload equals the receipt's canonical core. Sealing the receipt this way makes the cost basis non-repudiable by the endpoint that produced it and interoperable with every other family pillar.

> v0.1 used a bespoke `estimated_uj ‖ sequence ‖ nonce [‖ measured_uj]` preimage; v0.2 replaces it with JCR-1. This is the v0.1→v0.2 wire change.

## 4. The estimator of last resort (non-normative coefficients)

When only token counts are available — the common L4 case, where a remote ACP agent reports `input_tokens` / `output_tokens` but no energy — the estimator computes:

```
estimated_uj = input_tokens  * J_IN_uj
             + output_tokens * J_OUT_uj
```

and tags the reading `Estimator`. The coefficients are **non-normative** and tunable; the reference consumer ships datacenter-scale defaults where output dominates prefill. Reference values (illustrative, not part of conformance): `J_IN_uj = 200_000`, `J_OUT_uj = 2_000_000` (i.e. 0.2 J / 2.0 J per token). The point of the standard is not the constant — it is that the figure is reported, signed, and honestly tagged as an estimate.

## 5. From estimated to measured

Promoting a tier's receipts from `Estimator` to `HwShunt`/`ModelBased` is the work item that turns the meter "real" (ROADMAP v0.2). The receipt schema does not change; only the `provenance` tag and the presence of `measured_uj` improve as the platform gains a hardware interface that is live for the work (§2). A consumer's UI **SHOULD** surface the provenance so a reader can tell a measured joule from an estimated one.