open-standards/joule-code/spec/receipt.md

Joule Code — The Receipt

Normative sub-specification of ../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.