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]>
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# Joule Code — The Coding-Operation Cargo
|
|
|
|
Normative sub-specification of [`../SPEC.md`](../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](../../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).
|