open-standards/jouleclaw/jouleclaw-rs/crates/jouleclaw-jcr1/docs/JCR-1-spec.md

JouleClaw Receipt Specification (JCR-1) — Draft

Status: Draft · Version: 1 (jc_receipt: "1") · License: CC-BY-4.0 (text), Apache-2.0 (vectors)

An open, implementation-independent format for a signed, per-resolution thermodynamic receipt: proof that a given output cost a given number of joules, on hardware of a stated measurement honesty, verifiable by a third party who never ran the cascade.

This document formalizes the jouleclaw-prov receipt shape and closes the gap the reference crate leaves open: it defines (a) a canonical serialization, (b) a dependency-free signed envelope, and (c) a verification flow — so conformance does not depend on any JouleClaw code.

Key words MUST / SHOULD / MAY per RFC 2119.

---

1. Design invariants

1. Honesty over precision. A receipt MUST NOT claim accuracy finer than the worst energy counter in its span can deliver.
2. Determinism. The signed bytes MUST be reproducible bit-for-bit from the receipt fields. No field that cannot be canonically encoded may enter the signed core.
3. Producer/verifier separation. A producer mints and signs; a verifier needs only this spec, the public key, and (for joule re-validation) the conformance vectors. Verification MUST NOT require re-running proprietary code.
4. Additive evolution. Unknown fields MUST be ignored, never rejected. v1 only adds optional fields.

---

2. The Receipt object

Units are fixed: energy is microjoules as an unsigned 64-bit integer (joules_uj); floating point is forbidden in the signed core. Timestamps are RFC 3339 UTC. Hashes are lowercase hex BLAKE3-256. Tier tags are L0–L4.

2.1 Top-level fields

Field	Type	Req	Meaning
jc_receipt	string	MUST	Schema version. "1" for this spec.
id	string	MUST	Stable receipt id, monotonic per steward.
closed_at	string (RFC3339)	MUST	When the cascade walk closed.
input_hash	string (blake3-hex)	MUST	BLAKE3 of the normalized input that started the walk.
tier	enum L0..L4	MUST	Tier that closed the query.
joules_uj	u64	MUST	Total microjoules across all tiers walked.
energy_provenance	enum	MUST	Honesty tier of the worst counter in the span (§2.3).
steward	string	MUST¹	Signing identity (KERI AID or did:key). Binds receipt to issuer.
tools_touched	array⟨ToolTouch⟩	MAY	Per-tool energy, in call order.
claims	array⟨ClaimProvenance⟩	MAY	Sources that grounded the resolution. Empty for L0/L1.
tool_receipts	array⟨ToolReceipt⟩	MAY	Gateway-HMAC'd attestations (§2.6).
eoc_stage	string	MAY	EOC cascade stage label, if driven by one.
citations	array⟨Citation⟩	MAY	Span→source grounding (advisory).
token_attributions	array⟨TokenAttribution⟩	MAY	Per-token saliency (advisory, not in signed core — §3.3).

¹ steward is added by this spec; the reference crate carried the issuer in the outer Smart Byte envelope. Carrying it inline makes the receipt self-describing.

2.2 CascadeTier

L0 Cache (picojoules) · L1 Lawful/deterministic (nanojoules) · L2 Embed (sub-mJ) · L3 Model (joules) · L4 Wire/remote frontier (tens of J+). Wire tags L0–L4 are stable across versions.

2.3 Provenance (the honesty tag) — normative

Every energy reading carries one of:

• HwShunt — hardware reading: a shunt (Jetson INA3221), or a vendor energy counter (x86 RAPL MSR, NVIDIA cumulative-energy counter, Apple IOReport) while it is live for the domain it claims (below). Honest to the counter's resolution.
• ModelBased — vendor model estimate from freq/voltage/utilization (NVML power.draw, ROCm SMI). Millijoule-quantized at best.
• Estimator — JouleClaw static cost model. Wide tolerance by construction.

A vendor energy counter's reading is a real reading; the trust gap is provenance (which counter, which domain, whether it was live), not accuracy. Hence a live vendor counter is HwShunt, under this condition:

Liveness (MUST): 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. (JCR-1 v1 has no coverage field: a figure for a domain its counter does not read is not a HwShunt figure for that work at all.)

Apple IOReport's GPU rail is machine-wide (display compositing moves it with nothing of the metered work running), so it is not a partial reading of CPU work: where only the GPU rail is live, the reference implementation declines the counter and the CPU work is graded Estimator.

Worst-counter rule (MUST): Receipt.energy_provenance = the least-honest provenance among all readings contributing to joules_uj, ordered HwShunt > ModelBased > Estimator. A receipt whose span mixed a HwShunt GPU read and an Estimator NPU read MUST report Estimator.

Resolution floor (MUST): joules_uj MUST NOT be reported at finer resolution than the worst counter's resolution_uj. For ModelBased/Estimator the realistic floor is ~1000 µJ (1 mJ); values SHOULD be rounded to that quantum and the receipt MUST NOT imply sub-mJ precision it cannot support.

2.4 ClaimProvenance

source (string: URL/DOI/did) · content_hash (blake3-hex of claim bytes at fetch) · fetched_at (RFC3339) · trust_tier (u8, higher = more trusted). PROV-O mapping: each claim is a prov:Entity; source is the IRI, content_hash the wasGeneratedBy fingerprint.

2.5 ToolTouch

tool_id (string, e.g. mcp:filesystem/read, iac:fs.read, model:gemma4-9b-q5_k_m) · joules_uj (u64) · energy_provenance (enum).

2.6 ToolReceipt (gateway-attested)

Proves a tool was invoked through the gateway, not asserted by the model. tool_id · joules_uj · energy_provenance · minted_at (RFC3339) · gateway_id (string) · hmac_sha256_hex (64 hex chars). The HMAC (§5) is keyed by a gateway secret the model never holds.

2.7 Citation / TokenAttribution

Citation: text_span {start:u32, end:u32} (half-open byte range over the output the consumer holds) · source_chunk_id · exact_quote (verbatim, findable in the chunk). TokenAttribution: token_idx:u32 · chunk_scores: map<string,float> (provider-defined, ordinal not absolute) · optional method. Advisory only.

---

3. Canonicalization (the signed core)

3.1 Signed core vs advisory

The signed core is every MUST/MAY field in §2.1 except token_attributions (provider-defined floats, ordinal, not reproducible across methods). citations are in the core (strings/ints, deterministic, and grounding-relevant). token_attributions are carried alongside, outside the signature.

3.2 Canonical encoding

The signed core MUST be encoded as deterministic CBOR per RFC 8949 §4.2:

• Map keys are the field names as text strings, sorted by byte-wise lexicographic order of the UTF-8 key.
• Integers use the shortest form; joules_uj, start, end, token_idx, trust_tier are unsigned.
• Absent optional fields are omitted, not encoded as null.
• Arrays preserve producer order (tools_touched, claims, tool_receipts, citations are order-significant).
• No floats appear in the signed core (see §3.1).

A JSON projection (RFC 8785 JCS) MAY accompany the CBOR for debugging, but the signature is ALWAYS over the deterministic CBOR bytes.

3.3 The bytes to sign

CORE = det_cbor(signed_core_fields). The envelope signature (§4) is computed over CORE. Recomputing CORE from the parsed fields MUST yield identical bytes; a verifier that cannot reproduce CORE MUST treat the receipt as invalid.

---

4. The signed envelope

Receipts are sealed in a COSE_Sign1 structure (RFC 9052) so they interoperate with the RATS/CoRIM attestation tooling JouleClaw already uses.

COSE_Sign1 = [
  protected:   bstr .cbor { 1: alg, 4: kid },   ; alg = -8 (EdDSA) or -7 (ES256)
  unprotected: { },
  payload:     bstr,                            ; = CORE (det-CBOR signed core)
  signature:   bstr                             ; over Sig_structure per RFC 9052
]

• alg (MUST): EdDSA/Ed25519 (-8) is the default; ES256 (-7) permitted.
• kid (MUST): the steward identity — a KERI AID (recommended; supports key rotation/witnessing) or a did:key. The verifier resolves kid → public key out of band.
• payload: the deterministic-CBOR signed core (§3.3).

Key management is explicitly out of scope. KERI AID rotation is the RECOMMENDED substrate; any resolvable kid → public key mapping conforms.

---

5. Tool-receipt HMAC (sub-signatures)

Each ToolReceipt.hmac_sha256_hex is HMAC-SHA-256(gateway_key, payload), lowercase hex, where payload is the NUL-delimited canonical byte string:

tool_id ‖ 0x00 ‖ ascii(joules_uj) ‖ 0x00 ‖ prov_tag ‖ 0x00 ‖ minted_at ‖ 0x00 ‖ gateway_id

prov_tag ∈ {HwShunt,ModelBased,Estimator}; joules_uj as decimal ASCII. Verifiers look up the gateway key by gateway_id and recompute. Comparison MUST be constant-time. This sub-signature is independent of the envelope: it survives replay into a different context, attesting the gateway — not the model — observed the cost.

---

6. Verification flow

A verifier processes a received envelope in this order; failure at any step makes the receipt invalid (steps 1–4) or unverified-but-structurally-valid (step 5, when vectors are unavailable):

1. Structural. Parse COSE_Sign1; parse payload as det-CBOR; reject unknown jc_receipt major versions; ignore unknown fields.
2. Canonical re-encode. Recompute CORE from parsed fields; it MUST equal the payload bytes byte-for-byte.
3. Envelope signature. Resolve kid → public key; verify the COSE_Sign1 signature over CORE.
4. Tool receipts. For each tool_receipts[i], look up gateway_id's key and verify the HMAC (§5). A receipt asserting gateway-metered tools whose HMAC fails is invalid.
5. Honesty consistency. Check energy_provenance equals the worst provenance across tools_touched[*].energy_provenance and tool_receipts[*]; check joules_uj ≥ Σ tools_touched.joules_uj; check the resolution floor (§2.3).
6. (Optional) joule re-validation. If the verifier holds the conformance vector for this input_hash class, re-execute the cascade and confirm joules_uj falls within the drift band for the receipt's provenance tier (§7). Absent vectors, the receipt is signature-valid but joule-unverified.

---

7. Conformance

7.1 Drift bands (joule re-validation tolerance)

Re-execution will not reproduce joules exactly; the permitted band scales with honesty:

Provenance	Drift band on joules_uj
HwShunt	±10%
ModelBased	±35%
Estimator	±100% (order-of-magnitude only)

(Bands are the v1 defaults and are themselves part of the conformance vector; publish measured bands as data accrues rather than asserting these forever.)

7.2 Conformance levels

• Producer-conformant: emits receipts whose signed core re-encodes identically (§3) and whose energy_provenance/resolution obey §2.3.
• Verifier-conformant: implements steps 1–5 and reproduces published vectors.
• Vector-conformant standard: an independent implementation round-trips all 10 published conformance vectors (verify + re-encode), proving the spec — not the reference code — is the source of truth.

7.3 Vector slots (to populate + sign)

1 L0 cache hit · 2 L1 deterministic (no model) · 3 L1 IaC/tool-only · 4 L2 retrieval-grounded · 5 L3 local model · 6 L3 with citations · 7 L4 wire with claims · 8 mixed-span worst-counter (HwShunt+Estimator → Estimator) · 9 gateway tool-receipt HMAC · 10 promoted-skill (L3-derived → L1 cost). (Reference repo currently ships 3 of 10 — the gating work for "standard" status.)

---

8. Versioning & extensibility

jc_receipt is the schema major. Within "1", only optional fields are added, guarded so older verifiers ignore them. A breaking change increments to "2"; verifiers reject unknown majors at step 1. The L0–L4 tags and field semantics in §2 are frozen for v1.

9. Security & honesty considerations

• A receipt proves cost + provenance, not output correctness. Pair with the calibrated escalation gate so the answer is trustworthy, not just the bill.
• The signed core deliberately excludes advisory floats; do not infer that token_attributions are attested.
• The worst-counter rule is the spec's spine: a system that quietly upgrades an Estimator span to HwShunt to look precise is non-conformant and defeats the entire purpose. Honest meters are the whole product.
• HMAC keys are per-gateway secrets; envelope keys are per-steward. Compromise of one does not forge the other.

---

10. Worked example (JSON projection; signature over det-CBOR of the core)

{
  "jc_receipt": "1",
  "id": "rcpt-000128",
  "closed_at": "2026-05-31T18:04:22Z",
  "input_hash": "b3:9f2c...e1",
  "tier": "L1",
  "joules_uj": 4200,
  "energy_provenance": "HwShunt",
  "steward": "did:keri:EJ9...",
  "tools_touched": [
    { "tool_id": "iac:aws.ec2.describe", "joules_uj": 4200, "energy_provenance": "HwShunt" }
  ],
  "claims": [],
  "tool_receipts": [
    {
      "tool_id": "iac:aws.ec2.describe", "joules_uj": 4200,
      "energy_provenance": "HwShunt", "minted_at": "2026-05-31T18:04:22Z",
      "gateway_id": "gw-edge-7", "hmac_sha256_hex": "3f1a...c0"
    }
  ]
}

A deterministic motif (an IaC describe call) closed the query at L1 for 4.2 mJ, HwShunt-honest, with a gateway HMAC proving the gateway — not a model — ran it. No tokens burned; the receipt proves it.