# Joule Code — Lexicon

The controlled vocabulary for the Joule Code standard. Terms are normative where [`../SPEC.md`](../SPEC.md) uses them; this lexicon fixes their meaning so the spec, the reference library, and the conformance vectors agree. CC-BY-4.0.

## Core

- **Coding operation** (`CodingOp`) — the unit of cargo: a signed transition moving a source tree from a prior state to a successor state via an ordered edit set. Defined by base + edits, not by a restated result.
- **Operation id** (`op_id`) — the content address (BLAKE3-256 over deterministic CBOR) of a `CodingOp` excluding its signature.
- **Tree state** / **tree id** — a content-addressed snapshot of the relevant source; `tree_id` is BLAKE3-256 over `{ path: blob_id }`.
- **Signed operation** (`SignedOp`) — a `CodingOp` plus an Ed25519 signature over `op_id ‖ prior`, scoping authorization to one base.
- **Anchor** — where an edit applies: a byte range against the prior blob, or a content-addressed hunk (rename-stable).

## Cascade

- **Cascade** — the ordered tier list a request resolves through; resolution stops at the first tier that closes the request.
- **Tier** — `L0 Cache` (picojoules) · `L1 Lawful` (nanojoules) · `L2 Embed` (sub-millijoules) · `L3 Model` (joules) · `L4 Wire` (tens of joules). Inherited from JouleClaw.
- **Stage** — the implementation of one tier; exposes `try_resolve(req) -> Option<Resolution>`.
- **Close** — a stage closing a request: returning `Some(Resolution)`. The closing tier is recorded in the receipt.
- **Wire / L4 / frontier agent** — a remote coding agent (Claude Code, Gemini, Codex, ...) reached over ACP, with its credential held by the vendor's own client. The escape hatch, not the entry point.

## Receipt and energy

- **Receipt** — the signed, two-part energy record carried in a JWP frame accounting for one operation.
- **Energy** — `{ measured_uj?, estimated_uj, provenance }`, all integer microjoules.
- **Provenance** — the honesty tag on an energy reading: `HwShunt` (hardware-measured; requires `measured_uj`), `ModelBased` (calibrated model), `Estimator` (coarse constant).
- **JWP** — Joule Wire Protocol: the energy-aware framing that carries the receipt; cumulative energy is a first-class, signable frame field.
- **Joules per accepted change** — the standard's unit of merit; the substrate's falsifiable cost basis.

## Doctrine

- **Capability per joule** — the doctrine: minimize energy per accepted change, not parameters per model.
- **No capture** — no protocol token; core operation never requires a single steward's servers; frontier credentials never enter the protocol.
- **Ownerless** — identity lives in content addressing and conformance vectors, not a brand; the spec and reference code are permissively licensed; anyone may fork.
- **The offer** — the commercial layer (managed nodes, drivers, certification) that a steward operates *around* the substrate, never inside it.

## Collaboration (Research)

- **Cluster** — a known, signed-membership set of collaborators replicating operations by lockstep BFT.
- **Federated collaboration** — ownerless multi-endpoint editing: coding operations as Smart Byte envelopes, transported over CommunicationOS, shared via RemoteOS. Interface-level in v0.1.