# L3 binding — JouleClaw model tier → Joule Code cascade

A consumer **binding example**: how to wire JouleClaw's **L3 (Model)** tier into
the Joule Code cascade. It is a standalone workspace, so the standard's reference
library keeps no JouleClaw dependency.

A coding request that misses the cheaper tiers (L0 cache, L1 lawful, L2 embed) is
generated by a local model at L3, producing a content-addressed `CodingOp` and a
joules-class `Receipt`.

## Three backends, same slot

All implement JouleClaw's `jouleclaw_llm_cheap::LlmBackend`, so they drop into
the same cascade stage:

- **`EchoBackend`** (from JouleClaw) — deterministic, model-free; used by the
  unit tests so the wiring is verifiable with no model present.
- **`JouleclawRuntimeBackend`** (here) — runs the model **in-process on
  JouleClaw's own from-scratch GGUF tensor runtime** (`jouleclaw-runtime`): no
  external binary, no FFI. Tokenize → build the decode-step graph → compile
  against the registered kernels (`jouleclaw-backend-reference` /
  `-apple`) → autoregressive decode → detokenize, all in Rust the family wrote.
  This is the **default** backend for the `run` binary.
- **`LlamaCompletionBackend`** (here) — drives a real on-device GGUF via
  `llama-completion` (llama.cpp). Set `JOULE_CODE_L3_ENGINE=llama` to use it.

Either local path: no datacenter, no network. In production the cheapest capable
backend is chosen by `jouleclaw_dispatch::ModelBank`'s cost table.

## Run it against a local model

```bash
# Default: in-process on jouleclaw-runtime (the from-scratch tensor engine).
cargo run --release --bin run -- /path/to/model.gguf "Write a Rust function that reverses a string."
# or: JOULE_CODE_L3_MODEL=/path/to/model.gguf cargo run --release --bin run

# Use the llama.cpp shell-out backend instead:
JOULE_CODE_L3_ENGINE=llama cargo run --release --bin run -- /path/to/model.gguf "..."
```

The `run` binary generates with the local model, content-addresses the result as
a `CodingOp` (tier L3), and puts the **host** energy spent during the inference on
the receipt, tagged with the provenance of whatever metered it:

- **Apple Silicon whose IOReport CPU energy rail is live** — JouleClaw's IOReport
  counter, a live vendor energy counter: a real local measurement, tagged
  `HwShunt` (with `measured_uj` set).
- **Apple Silicon whose CPU rail is not live** — macOS 27.0.1 for an unprivileged
  process, observed on an M5 Max and an M3 Ultra — JouleClaw's load-average
  estimator, tagged `Estimator`. Not a measurement.
- **Anywhere else**, Linux and Windows included — the token-count estimate,
  tagged `Estimator`. This binding builds `jouleclaw-energy` with the `ioreport`
  feature only, so it reads no RAPL or NVML counter even where one exists.

The printout names the meter that ran and the IOReport status, and says whether
the figure was measured or estimated.

Verified live: the llama.cpp path against a local 350M GGUF, and the in-process
from-scratch runtime against `ternary-bonsai-1.7b-q2_0` (qwen3, Q2_0) — real text
generated, a real `op_id`, the cascade closing at L3.

## Tests

```bash
cargo test   # EchoBackend path — no model required

# In-process from-scratch runtime against a real GGUF (opt-in):
JOULE_BONSAI=/path/to/ternary-bonsai-1.7b-q2_0.gguf \
  cargo test --release --test runtime_l3 -- --ignored --nocapture
```