# JCR-1 Conformance Vector Suite

A reference test suite for the **JouleClaw Receipt Spec (JCR-1)**. Ten signed
receipt vectors plus a standalone verifier. A second implementation in any
language is **vector-conformant** when it reproduces these results — which is the
gate that turns JCR-1 from "a format JouleClaw uses" into "a standard."

## Files
- `jcr1-vectors.json` — the 10 vectors. Each carries the receipt (JSON
  projection), the deterministic-CBOR signed core (hex), and the COSE_Sign1
  envelope (hex).
- `jcr1-test-keys.json` — the fixed Ed25519 keypair and gateway HMAC keys. **Test
  material only**, published for reproducibility.
- `jcr1-verify.py` — standalone reference verifier. Depends only on `cbor2` and
  `cryptography` (no JouleClaw code).

## Run
```
pip install cbor2 cryptography
python3 jcr1-verify.py jcr1-vectors.json jcr1-test-keys.json
```
Expected: `10/10 vectors verified`.

## What each vector exercises (JCR-1 7.3 slots)
1. **L0** cache hit — picojoule class, no tools.
2. **L1** deterministic primitive (arithmetic) — no model.
3. **L1** IaC/tool-only — a `terraform`-style describe closes the query, **zero
   tokens**, with a gateway HMAC. (The spec's worked example.)
4. **L2** retrieval-grounded — claim provenance + a span citation.
5. **L3** local model — joule class, HwShunt GPU.
6. **L3** retrieval + model on a **ModelBased** span, mJ-floored (toy figures,
   like every vector here: not an IOReport or any other reading).
7. **L4** remote frontier RPC — **Estimator** (remote energy unmeasurable).
8. **Mixed span** HwShunt + Estimator → worst-counter rule forces **Estimator**.
9. **Gateway HMAC** — two metered tool calls, both signed by `gw-edge-9`.
10. **Promoted skill** — same `input_hash` as vector 5, now closing at **L1 for
    9 µJ** instead of 2.5 J. The turnover/“enzyme” claim, made checkable.

Vectors 5 and 10 share an `input_hash` on purpose: side by side they show one
query class collapsing from L3 (2,500,000 µJ) to L1 (9 µJ) after promotion — a
~270,000× drop on that class, the per-deployment decay loop in a single diff.

## What the verifier checks
1. **Re-encode determinism** — the signed core must re-serialize to identical
   bytes (RFC 8949 §4.2.1 canonical CBOR).
2. **Envelope signature** — COSE_Sign1 (RFC 9052), EdDSA/Ed25519, `kid` = steward.
3. **Gateway HMACs** — each `tool_receipt` HMAC-SHA-256 recomputed from the
   NUL-delimited canonical payload.
4. **Honesty consistency** — `energy_provenance` equals the worst counter in the
   span; `joules_uj ≥ Σ tools_touched`; ModelBased/Estimator values respect the
   1 mJ resolution floor.

## It has teeth (negative tests, all DETECTED)
- Understating `joules_uj` in the body → re-encode mismatch.
- Claiming `HwShunt` on an Estimator span → envelope payload mismatch (can't
  forge without the steward key).
- Forging a tool-receipt joule count → re-encode mismatch / HMAC fail.
- One-bit tamper of the envelope → Ed25519 verification fail.

## Canonicalization note (clarifies JCR-1 §3.2)
The signed core uses **RFC 8949 §4.2.1 core deterministic encoding**: map keys
sorted length-first then bytewise on the encoded key (as `cbor2 canonical=True`
emits). A second implementation MUST match this ordering exactly, or step 1 fails.
This is the precise reading of §3.2 and should be folded into the spec as an
erratum.

## Conformance levels
- **Producer-conformant** — emits receipts whose signed core re-encodes
  identically and whose provenance/resolution obey §2.3.
- **Verifier-conformant** — implements checks 1–4 above.
- **Vector-conformant standard** — an *independent* implementation verifies all
  10 vectors here. That is the milestone that makes JCR-1 a standard rather than
  a house format.

> Reminder from the strategy: a receipt proves **cost + provenance, not output
> correctness**. Pair JCR-1 with the calibrated escalation gate so the *answer*
> is trustworthy, not only the bill.