# Joule Code — The Cascade Binding

Normative sub-specification of [`../SPEC.md`](../SPEC.md) §1.1 and §5. CC-BY-4.0.

The cascade is how a coding request resolves into a `CodingOp` (or a non-mutating answer) at the lowest energy tier that can close it. The agent schema implementing the tiers is [JouleClaw](../../jouleclaw/); Joule Code fixes the *binding* of that cascade to coding requests.

## 1. Tiers

```
Tier = L0 | L1 | L2 | L3 | L4
```

| Tier | For a coding request | Energy class |
|---|---|---|
| L0 Cache | content-addressed op cache: identical `(prior, intent)` → cached `CodingOp` | picojoules |
| L1 Lawful | deterministic primitive: rename, format, organize imports, mechanical refactor | nanojoules |
| L2 Embed | embedding + hybrid retrieval: locate the symbol/snippet, recall a prior op | sub-millijoules |
| L3 Model | local model (open-weight SSM/ternary, e.g. vLLM) generates the edit | joules |
| L4 Wire | remote frontier coding agent over ACP (Claude Code / Gemini / Codex / ...) | tens of joules |

## 2. Stage interface

```
trait Stage {
    fn tier(&self) -> Tier;
    fn try_resolve(&self, req: &Request) -> Option<Resolution>;
}

Resolution {
    op:      Option<CodingOp>,   // None for a non-mutating answer (e.g. a query)
    answer:  Option<String>,
    receipt: Receipt,            // see ../spec/receipt.md
}
```

A `Cascade` holds stages in strictly ascending tier order. `resolve(req)` calls `try_resolve` in order and returns the **first** `Some`. This is the stop-at-first-close rule (SPEC §1.1): a runtime **MUST NOT** consult a higher tier once a lower tier returns `Some`, and the returned `Resolution.receipt.tier` **MUST** equal the closing stage's `tier()`.

A runtime **MAY** omit tiers it does not implement; the cascade simply skips absent stages. A runtime with only an L4 stage is conformant but maximally energy-inefficient — it has opted out of the doctrine's benefit, not its rules.

## 3. The L4 (ACP) binding

L4 stages drive a **remote frontier coding agent** through the Agent Client Protocol. The Joule Code runtime is the ACP client; the agent is an ACP server launched by the vendor's own logged-in CLI. Normative requirements:

1. The credential to the frontier agent **MUST** live in the vendor's client, not the protocol (SPEC §1.3). The runtime launches the CLI; it does not transport a token.
2. When the ACP agent reports token usage, the L4 stage **MUST** feed it to the receipt's `estimated_uj` via the estimator (`Provenance: Estimator`) unless a hardware-measured figure is available for the local portion of the work.
3. The L4 stage **MUST** record which leg answered (agent id) so the receipt is attributable.

## 4. Determinism

Tier selection is integer-only (SPEC §4): budgets, thresholds, and gradients are integers. A cascade given the same stage outcomes **MUST** select the same closing tier across implementations — the property the `cascade_vectors.json` conformance pack checks (SPEC §8 C4).