# 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 hardware interface
  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 (RAPL, Apple SMC/IOReport, an external shunt). 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.

## 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. A consumer's UI **SHOULD** surface the provenance so a reader can tell a measured joule from an estimated one.