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

2.9 KiB

Raw Permalink Blame History

Joule Code — The Coding-Operation Cargo

Normative sub-specification of ../SPEC.md §2. CC-BY-4.0.

A coding operation (CodingOp) is the unit of cargo Joule Code carries: a signed transition that moves a source tree from a prior state to a successor state. It is structurally a Smart Byte whose payload is application-typed as a code change.

1. Tree state

A tree state is a content-addressed snapshot of the relevant source. Its content address (tree_id) is BLAKE3-256 over the deterministic-CBOR encoding of an ordered map { path: blob_id }, where blob_id is BLAKE3-256 of the file bytes. An implementation MAY scope the tree to the files an operation touches plus their transitive context, provided the scope is recorded; v0.1 conformance only exercises explicit small trees.

2. `CodingOp`

CodingOp {
  alg:    u8,            // 0x01 = Ed25519 (RFC 8032)
  prior:  ContentId,     // tree_id this op builds on
  edits:  [Edit],        // ordered, non-empty
  author: [u8; 32],      // Ed25519 verifying key
  intent: String,        // UTF-8 request description (advisory)
  tier:   Tier,          // L0..L4 that closed the request
}

op_id = BLAKE3-256(canonical_cbor(CodingOp)).

2.1 `Edit`

Edit {
  path:        String,       // tree-relative, forward-slash, NFC-normalized
  anchor:      Anchor,       // where the edit applies
  replacement: Bytes,        // the new bytes for the anchored region
}

Anchor = ByteRange { start: u64, end: u64 }   // half-open, against the prior blob
       | Hunk      { hunk_id: ContentId }      // content-addressed region (rename-stable)

Edits MUST be disjoint and MUST be listed in ascending (path, start) order so the canonical form is unique. Applying edits to prior yields the successor tree; an implementation MAY compute the successor tree_id and include it out of band, but it is not part of op_id (the op is defined by base + edits, not by a restated result).

3. `SignedOp`

SignedOp { op: CodingOp, sig: [u8; 64] }

sig = Ed25519_sign(author_secret, op_id ‖ prior). Binding prior into the preimage scopes the signature to one base: the same edits authorized against a different tree state produce a different preimage and a different signature, so an operation cannot be replayed onto a tree it was not authored against. Verification recomputes op_id from the canonical form and checks sig against author over op_id ‖ prior.

4. Negative cases (conformance)

A conformant verifier MUST reject:

a SignedOp whose sig verifies against a prior different from the one in op (replay onto a different base);
a SignedOp whose edits were altered after signing (recomputed op_id no longer matches);
a CodingOp with overlapping or mis-ordered edits (non-canonical);
a CodingOp whose alg is unknown to the verifier (fail closed; do not guess an algorithm).

2.9 KiB Raw Permalink Blame History