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]>
50 lines
2.9 KiB
Markdown
50 lines
2.9 KiB
Markdown
# Joule Code — The Cascade Binding
|
|
|
|
Normative sub-specification of [`../SPEC.md`](../SPEC.md) §1.1 and §5. CC-BY-4.0.
|
|
|
|
The cascade is how a coding request resolves into a `CodingOp` (or a non-mutating answer) at the lowest energy tier that can close it. The agent schema implementing the tiers is [JouleClaw](../../jouleclaw/); Joule Code fixes the *binding* of that cascade to coding requests.
|
|
|
|
## 1. Tiers
|
|
|
|
```
|
|
Tier = L0 | L1 | L2 | L3 | L4
|
|
```
|
|
|
|
| Tier | For a coding request | Energy class |
|
|
|---|---|---|
|
|
| L0 Cache | content-addressed op cache: identical `(prior, intent)` → cached `CodingOp` | picojoules |
|
|
| L1 Lawful | deterministic primitive: rename, format, organize imports, mechanical refactor | nanojoules |
|
|
| L2 Embed | embedding + hybrid retrieval: locate the symbol/snippet, recall a prior op | sub-millijoules |
|
|
| L3 Model | local model (open-weight SSM/ternary, e.g. vLLM) generates the edit | joules |
|
|
| L4 Wire | remote frontier coding agent over ACP (Claude Code / Gemini / Codex / ...) | tens of joules |
|
|
|
|
## 2. Stage interface
|
|
|
|
```
|
|
trait Stage {
|
|
fn tier(&self) -> Tier;
|
|
fn try_resolve(&self, req: &Request) -> Option<Resolution>;
|
|
}
|
|
|
|
Resolution {
|
|
op: Option<CodingOp>, // None for a non-mutating answer (e.g. a query)
|
|
answer: Option<String>,
|
|
receipt: Receipt, // see ../spec/receipt.md
|
|
}
|
|
```
|
|
|
|
A `Cascade` holds stages in strictly ascending tier order. `resolve(req)` calls `try_resolve` in order and returns the **first** `Some`. This is the stop-at-first-close rule (SPEC §1.1): a runtime **MUST NOT** consult a higher tier once a lower tier returns `Some`, and the returned `Resolution.receipt.tier` **MUST** equal the closing stage's `tier()`.
|
|
|
|
A runtime **MAY** omit tiers it does not implement; the cascade simply skips absent stages. A runtime with only an L4 stage is conformant but maximally energy-inefficient — it has opted out of the doctrine's benefit, not its rules.
|
|
|
|
## 3. The L4 (ACP) binding
|
|
|
|
L4 stages drive a **remote frontier coding agent** through the Agent Client Protocol. The Joule Code runtime is the ACP client; the agent is an ACP server launched by the vendor's own logged-in CLI. Normative requirements:
|
|
|
|
1. The credential to the frontier agent **MUST** live in the vendor's client, not the protocol (SPEC §1.3). The runtime launches the CLI; it does not transport a token.
|
|
2. When the ACP agent reports token usage, the L4 stage **MUST** feed it to the receipt's `estimated_uj` via the estimator (`Provenance: Estimator`) unless a hardware-measured figure is available for the local portion of the work.
|
|
3. The L4 stage **MUST** record which leg answered (agent id) so the receipt is attributable.
|
|
|
|
## 4. Determinism
|
|
|
|
Tier selection is integer-only (SPEC §4): budgets, thresholds, and gradients are integers. A cascade given the same stage outcomes **MUST** select the same closing tier across implementations — the property the `cascade_vectors.json` conformance pack checks (SPEC §8 C4).
|