open-standards/joule-code

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 carries value, 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:

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; 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 — the normative specification (RFC 2119). The coding-operation cargo, the cascade binding, the receipt schema, and the conformance contract.
• spec/ — sub-specifications: the coding-operation cargo type, the cascade binding, the receipt format, and the federated collaboration binding.
• vocab/ — the controlled vocabulary (LEXICON.md).
• conformance/ — signed wire vectors. A standard is conformant if it round-trips these.
• 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 §9 and respected when sequencing work.

Related

• JouleClaw — the energy-optimised AI runtime; Joule Code's agent schema. The cascade tiers and the receipt provenance discipline are JouleClaw's.
• 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 — 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/) is Apache-2.0 (LICENSE). Specification text (SPEC.md, spec/, vocab/) is CC-BY-4.0 (LICENSE-SPEC). The wire format and the right to fork are public.