Watch

David Charlot b838b86a8b joule-code: stand up the Joule Code standard (v0.1.0 draft)

Joule Code is the coding cargo class of the substrate: a coding operation —
an edit, refactor, or generated function — is a content-addressed, signed
transition over a source tree, resolved through the energy-tiered cascade
(L0 Cache → L1 Lawful → L2 Embed → L3 Model → L4 Wire, stop-at-first-close)
with a signed JWP receipt (measured + estimated µJ, honest Provenance) per
operation. The agent schema is JouleClaw; L4 frontier agents are reached over
ACP with the credential held by the vendor's own client — no protocol token,
no required contact with any single company.

Stands up the standard to the family schema:
- README, SPEC.md (RFC-2119 normative), dual licence (Apache-2.0 code /
  CC-BY-4.0 spec), ROADMAP, CONTRIBUTING, CHANGELOG.
- spec/: cargo (the coding-operation type), cascade (the tier binding),
  receipt (the JWP energy record), collab (federated, interface-level/Research).
- vocab/LEXICON.md.
- conformance/v1/: C1 content-addressing, C2 signing, C3 receipt, C4 cascade
  vectors + VERSIONS + regeneration; real Ed25519 RFC-8032 KATs, derived
  fields regenerated against the reference library.
- joule-code-rs/: lean reference library (schema, cargo, receipt, cascade,
  conformance). cargo test --workspace passes; the conformance harness runs
  11 pass / 0 fail / 7 skip (derived fields pending regeneration).

Single-endpoint operation is the v0.1 surface; federated collaboration is
specified at interface level and classified Research. Registers the standard
in the family README.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

2026-06-02 14:07:00 -04:00

3.2 KiB

Raw Permalink Blame History

Joule Code — Lexicon

The controlled vocabulary for the Joule Code standard. Terms are normative where ../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.

3.2 KiB Raw Permalink Blame History