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]>
2.9 KiB
Joule Code — The Cascade Binding
Normative sub-specification of ../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; 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:
- 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.
- When the ACP agent reports token usage, the L4 stage MUST feed it to the receipt's
estimated_ujvia the estimator (Provenance: Estimator) unless a hardware-measured figure is available for the local portion of the work. - 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).