# JouleClaw Hydra-Client conformance

Cross-language conformance for the third-generation Hydra client.
Rust + Python + Go reference implementations all produce
byte-for-byte identical BLAKE3 input/output hashes against the
vectors below.

## Files

| File | What |
|------|------|
| [`call-reports.json`](call-reports.json) | 5 dispatch vectors + 4 SHACL-validation vectors. Each pairs an input (Hydra API doc + operation name + payload) with the canonical expected CallReport (tool_id, status, input_hash, output_hash, status_matches_contract, body). |

## How the three implementations agree

Every implementation:

1. Parses the Hydra `ApiDocumentation` from the JSON-LD in the vector.
2. Looks up the operation by `jc_tool_id`.
3. Validates the input against the embedded SHACL shapes for `https://example.com/Tool#AppendInput` (open-world default elsewhere).
4. Dispatches via an echo-mode `MockTransport` — the same canonical form: `{ "echo": <input> }`, status 200, no measured energy.
5. Computes BLAKE3 over lexically-sorted, no-whitespace canonical JSON of input and output.
6. Returns a `CallReport` with the hex BLAKE3 digests.

The three implementations live at:

| Language | Path |
|----------|------|
| Rust     | [`crates/jouleclaw-hydra-client/src/lib.rs`](../src/lib.rs) |
| Python   | [`crates/jouleclaw-hydra-client/clients/python/jclaw_hydra/`](../clients/python/jclaw_hydra/) |
| Go       | [`crates/jouleclaw-hydra-client/clients/go/`](../clients/go/) |

## Running

```bash
# Rust (regenerator; also the oracle)
cargo run -p jouleclaw-hydra-client --example gen_conformance_vectors

# Python (requires `pip install blake3`; the energy-grade tests also pytest)
python3 crates/jouleclaw-hydra-client/clients/python/tests/test_conformance.py
python3 -m pytest crates/jouleclaw-hydra-client/clients/python/tests/

# Go (uses lukechampine.com/blake3 via go.mod)
cd crates/jouleclaw-hydra-client/clients/go && go test -v ./...
```

All three MUST print `PASS` for every vector. A mismatch on ANY
implementation is a divergence to fix on that side — the canonical
oracle is the Rust producer (which is what generates the vectors).

## Scope

- **In:** the cross-language Hydra-client surface — Hydra parse,
  SHACL validate, dispatch via Transport, BLAKE3 hash over
  canonical JSON, CallReport emission.
- **Out:** the wire form of cascade receipts and policy receipts
  is covered by separate conformance suites at
  `crates/jouleclaw-jcr1/conformance/` and
  `crates/jouleclaw-policy-receipt/conformance/`. The Hydra client
  produces `ToolTouch`-shaped touches that drop into those streams;
  it does not itself produce signed receipts.