| Filename | Latest commit message | Latest commit date |
|---|---|---|
078aeb3c2a
All checks were successful
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 59s
`EnergyLabel` is an A–G enum with an ordering and a description, and nothing in
this workspace ever *derived* one — every use supplies a letter the caller had
already decided (`build_sample("svc-1", 0.35, EnergyLabel::A)`). The label was a
container for someone else's judgement, which is the one shape a rating must not
have. The only threshold rule that did exist,
`EuComplianceReport::is_compliant`, is a hardcoded `pue < 1.5 && renewable_pct
>= 50.0`: two magic floats with no provenance, no version, and no way to band
anything.
`BandingScale::rate` is the missing function. What matters is less the
arithmetic than what it refuses to let a caller do.
**A letter is not a rating.** Two facilities both rated "B" under different
threshold sets are not comparable, and nothing about the letter says so. A
`Rating` therefore cannot be constructed without its scale: it carries the
`scale_id`, the metric, the unit, and the measured value, so a reader
re-derives the letter rather than trusting it. `comparable_with` is an explicit
check, and `better_than` returns `None` for incomparable ratings rather than
`Ordering::Equal` — refusing to rank is a different answer from ranking equal,
and collapsing them is exactly how a bare enum invites the mistake.
**A revision is a different scale.** Because the `scale_id` travels inside every
rating, re-tuning thresholds cannot silently re-band history — the test pins a
value that is C under v1 and D under v2, and shows the two ratings do not
compare.
**Scales are data, not match arms.** A new scale is a value, not a recompile.
**Integers, in a declared unit.** Thresholds are `u64` in a unit the scale names
(milli-PUE rather than `1.5`), matching the receipt family's discipline: a
float boundary makes the band depend on how the value was parsed, and band edges
are precisely where that bites.
**Boundaries earn the better band**, stated once and tested at every edge, so
"on the line" is not left to the reader.
**A non-monotonic scale cannot rate at all.** Overlapping boundaries would
assign different letters to one value depending on evaluation order, so
`validate` rejects them and `rate` refuses rather than emitting a band from a
scale that cannot rank. A scale must also carry an id and a unit, since a rating
that cannot cite its scale is back to being a bare letter.
No scale is shipped as canonical. The examples in the tests are named
`example.*` on purpose: which thresholds are correct for a given metric is a
policy question this crate has no standing to settle, and baking one in would
repeat the `pue < 1.5` mistake with more ceremony.
Verified: 43 crate tests pass (7 new), no clippy warnings in the new file.
|
||
| .. | ||
| conformance/v1 | ||
| jouleclaw-rs | ||
| vocab | ||
| LICENSE | ||
| README.md | ||
| ROADMAP.md | ||
| SPEC.md | ||
JouleClaw — Energy-Optimized AI Runtime
The substrate for AI that costs Joules, not tokens.
Capability per Joule, not capability per parameter.
What JouleClaw is
JouleClaw is a pure-Rust, omni-modal AI runtime + harness + agentic layer governed by Transaction Science as an open standard (5th in the open-standards quartet, alongside OpenPay, Smart Byte, EOC, and WAI).
Every operation JouleClaw performs walks an explicit energy-tiered cascade, top to bottom, stopping at the first stage that closes the query:
| Tier | Name | Cost class | What runs here |
|---|---|---|---|
| L0 | Cache | picojoules | Content-addressed cache hits |
| L1 | Lawful | nanojoules | Deterministic, pre-compiled primitive (text/code only) |
| L2 | Embed | sub-millijoules | Matryoshka embeddings + nearest-neighbor + hybrid search |
| L3 | Model | joules | Local SSM / ternary / multimodal / diffusion / etc. |
| L4 | Wire | tens of joules | Remote frontier RPC (escape hatch only) |
L1 (Lawful) is only meaningful for text and code modalities. For image, audio, video and 3D generation, the cascade collapses to L0 / L2 / L3 / L4 — the energy savings come from caching plus dispatch to the cheapest model that meets the quality bar.
Why JouleClaw exists
The mainstream "agentic AI" ecosystem treats inference as the entry point. Every state shift, every tool call, every routing decision runs through a 70-billion-parameter stochastic engine, burning kilojoules to do work that deterministic compute or a hot cache could resolve for microjoules.
JouleClaw inverts the default. Inference is the last resort, not the first. Frozen model weights are less trustworthy than current world state; fresh, provenance-stamped retrieval beats synthesis from training cuts. Every operation is metered in microjoules where the hardware permits it, and in millijoules where it doesn't — the spec is honest about the floor on every platform.
The thermodynamic circuit breaker is the safety mechanism. Set an energy budget; when measured consumption exceeds the budget, the breaker trips and the operation halts. Hallucination loops cannot survive an honest joule ledger.
What's here
| Path | Contents |
|---|---|
SPEC.md |
JouleClaw v1 spec — cascade tiers, energy contract, receipt |
CHARTER.md |
Stewardship pattern (shared across open-standards) |
jouleclaw-rs/ |
Apache-2.0 Rust reference implementation |
spec/ |
Tier specifications, energy provenance, receipt format |
conformance/v1/ |
Signed wire vectors for cross-implementation verification |
Reference implementation
jouleclaw-rs/ is the Apache-2.0 reference implementation in Rust. It
runs on Apple Silicon (M3/M4/M5 with UMA + Metal 4 Tensor APIs), AMD Strix
Halo / Ryzen AI Max, Intel Lunar Lake, NVIDIA Jetson, and discrete
NVIDIA / AMD GPUs.
It is omni-modal: text, code, vision, audio, video, image diffusion, 3D Gaussian splatting, and cross-modal fusion all dispatch through the same energy-tiered cascade.
The MCP tool surface is a JCP consumer: jouleclaw-jcp wraps any
jouleclaw-mcp metered tool so every dispatch is decided by the JCP runtime
against a signed, metered Grant before a byte reaches the tool — the tool's
identity is the content-addressed resource, the call's energy estimate is
debited from the grant's joule budget, and every decision (allow and deny
alike) seals as a JCR-1 receipt. An injected instruction can name an ungranted
tool; it cannot make the gate dispatch it.
Status
v0.1.0 reference implementation in active development. The spec is draft status. Cross-implementation conformance vectors will land with v1.0.0.
License
- Code: Apache-2.0 (see
LICENSE) - Spec text: CC-BY-4.0 (see
spec/LICENSE)