open-standards/joule-code/README.md

# Joule Code

A carrier for coding work. Federated, energy-attributed, owned by no one.

Joule Code is the **coding cargo class** of the Transaction Science substrate. Where [Smart Byte](../smart-byte/) carries value, [EOC](../eoc/) carries compute, and Ambient Mobile (CommunicationOS) carries signal, Joule Code carries **agentic coding operations** — an edit, a refactor, a generated function, a review — as a content-addressed, signed transition with its energy cost intrinsic.

A coding operation is not a chat turn and not an opaque API call. It is a **vesicle** carrying exactly five things: identity (the blake3 content address of its canonical serialization), provenance (the prior tree state it builds on, and the author key that authorized it), an ownership chain (signature-bound transitions, so a change cannot be replayed onto a different base), cargo (the change itself — an edit set against a tree), and a two-part joule cost (`measured + estimated`, with an honest provenance tag on every reading). Operations resolve through an explicit **energy-tiered cascade** — cache, then deterministic, then retrieval, then a local model, then a remote frontier agent as the last resort — and **stop at the first tier that closes the request**. Inference is the escape hatch, not the entry point.

The substrate is intentionally **ownerless**: no protocol-level token, permissive licensing on the spec text and reference code, and conformance test vectors so any implementer can verify canonicity without a trust relationship with the authors. A conforming Joule Code endpoint drives a vendor's own logged-in coding agent (the vendor CLI owns its token; the protocol never sees a credential), measures the energy of every operation, and emits a signed receipt — with no contact with any single company's servers as a condition of operation. Transaction Science is one steward: it publishes the spec, ships a reference implementation, and operates commercial services around the substrate — not its proprietor.

## The doctrine

**Capability per joule, not capability per token.** The durable layer of a coding tool is not token resale or editor convenience — both are commoditized. It is the substrate, measured in **joules per accepted change**. "Make it work" and "don't waste energy" are the same optimization: thrash is simultaneously the bug and the energy leak.

Three consequences, normative in [`SPEC.md`](SPEC.md):

1. **The cascade.** Every coding request dispatches through `L0:Cache → L1:Lawful → L2:Embed → L3:Model → L4:Wire` and stops at the first tier that closes it. The agent schema is [JouleClaw](../jouleclaw/); the remote frontier agents (Claude Code, Gemini, Codex, ...) are L4, reached over the Agent Client Protocol (ACP).
2. **The receipt.** Every operation reports a two-part energy cost in microjoules — `measured + estimated` — with a `Provenance` tag (`HwShunt | ModelBased | Estimator`) on every reading, sealed as a JCR-1 envelope (canonical det-CBOR + COSE_Sign1/EdDSA — the family's shared signed-receipt format). The spec never claims an accuracy the platform cannot deliver.
3. **No capture.** No protocol token. The credential to a frontier agent lives in the vendor's own CLI, never in the protocol. A conforming endpoint performs its core function without phoning home to any single company.

## Contents

- [`SPEC.md`](SPEC.md) — the normative specification (RFC 2119). The coding-operation cargo, the cascade binding, the receipt schema, and the conformance contract.
- [`spec/`](spec/) — sub-specifications: the coding-operation cargo type, the cascade binding, the receipt format, and the federated collaboration binding.
- [`vocab/`](vocab/) — the controlled vocabulary ([`LEXICON.md`](vocab/LEXICON.md)).
- [`conformance/`](conformance/) — signed wire vectors. A standard is conformant if it round-trips these.
- [`joule-code-rs/`](joule-code-rs/) — the Rust reference library: the protocol crates (schema, cargo, receipt, cascade, conformance), plus `joule-code-jcp` — the cascade as a **JCP consumer**: every stage consultation is decided by the JCP runtime against a metered Grant *before* the stage runs (the tier is the action, the source tree the content-addressed resource, the tier's energy class the debit), so the L4 escape hatch to a remote frontier agent exists only when a signed grant names it and can pay for it. Every consultation, allowed and denied, seals as a JCR-1 receipt. `joule-code-joulecontract` binds an operation to the sibling **JouleContract** standard: the edit set is the contract's frame (an out-of-frame edit is caught at the boundary and recorded, not suppressed), the tier cost is the ceiling, and JCR provenance maps downward-only onto the energy classes (`Estimator` can never serialize as `Metered`). `joule-code-remediate` is the reference **verified-fix harness** (`joule-fix`): it scans a Rust workspace, remediates at the cheapest sufficient tier (L1 lawful codemods first — deterministic, zero inference), and gates every fix behind a pipeline whose stages ARE the contract's obligations — baseline capture, build, no-new-test-failures, lint-delta, frame confinement, diff guard — each discharged with its actual outcome. A fix that fails any gate is reverted and never ships, and the refusal itself produces a receipt. The run's energy is measured by the sibling sandbox standard's hardware meter and sealed as a JCR-1 envelope that serves as the JouleContract receipt's meter attestation — one standard's receipt is the other's evidence — and the harness reports **energy per verified fix** from hardware counters, not estimates. A **methodology layer** makes spec-driven development auditable on top of the protocol: `joule-code-spec` is the signed, content-addressed **Spec** — intent plus individually addressable clauses (requirements, constraints, and first-class non-goals), with a signed Citation binding each operation to the clauses it implements and a deterministic coverage audit that names open obligations and flags any cited non-goal. `joule-code-review` makes two-stage review (spec-compliance, then quality) a signed artifact where **separation of duties is a signature check**: a review whose reviewer key equals the operation's author key is structurally void — self-review cannot stand, human or agent. `joule-code-reviewer` is the independent reviewer *agent* that produces those reviews — a distinct principal making a real, falsifiable judgment (it refuses to review its own work, and it can request changes), arranged as a cheapest-sufficient cascade: a learned tier (defect patterns a model has already taught it, applied model-free), a structural tier, and an optional semantic model tier behind a subprocess seam. The model's *rejections* compile into learned skills so a recurring defect is caught for nanojoules — the fix harness's amortization moat, applied to review — while *approvals* are never cached, because a stale approval is a silent-failure lane. `joule-code-release` is the **total door**: a release certifies only when all four gates — spec coverage, contract discharge, two-stage review, attested build — are present and satisfied, and otherwise refuses with the missing gate named. Two terminal states, no third. This is the lean library a third party implements against — not an editor.

## Reference implementation and consumers

`joule-code-rs/` is the protocol library. The flagship **consumer** is a hard fork of the Zed editor ("agent-zed"), which drives logged-in vendor coding agents over ACP, meters every turn, and surfaces the joule receipt in its UI — the SOTA editor surface for the standard. The protocol is what any party implements; the editor is one (high-quality) consumer, the way `wai-rs` is the standard and CommunicationOS is a consumer.

## Status

v0.2.0 draft. Specification core published (cargo, cascade binding, receipt); reference library lands the schema, cargo, receipt, and cascade crates with a conformance harness. Receipts seal as **JCR-1** envelopes (canonical det-CBOR + COSE_Sign1, EdDSA), the signed-receipt format shared across the family, so a Joule Code receipt verifies under existing JCR-1 tooling. The conformance vectors are real, cryptographically computed values (the harness passes the whole pack with no skips). The federated-collaboration binding is **Research** and is specified at the interface level only — single-endpoint operation is the current surface.

Readiness is classified per component (Solid / Engineering / Research / Theory) in [`SPEC.md`](SPEC.md) §9 and respected when sequencing work.

## Related

- [JouleClaw](../jouleclaw/) — the energy-optimised AI runtime; Joule Code's **agent schema**. The cascade tiers and the receipt provenance discipline are JouleClaw's.
- [Smart Byte](../smart-byte/) — the value carrier; a Joule Code operation is structurally a Smart Byte whose cargo is a code change. Identity, signing, and lockstep replication are shared.
- [EOC](../eoc/) — the energy-optimised compute substrate; the cheap cascade tiers (cache / retrieval) follow EOC's resolution discipline.
- CommunicationOS — the signal carrier; the federated-collaboration binding transports coding operations between collaborators over its group-state and media paths.

## Licence

Reference code (everything under [`joule-code-rs/`](joule-code-rs/)) is **Apache-2.0** ([`LICENSE`](LICENSE)). Specification text (`SPEC.md`, `spec/`, `vocab/`) is **CC-BY-4.0** ([`LICENSE-SPEC`](LICENSE-SPEC)). The wire format and the right to fork are public.