b838b86a8b
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]>
39 lines
3.2 KiB
Markdown
39 lines
3.2 KiB
Markdown
# 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.
|