# 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).