| Filename | Latest commit message | Latest commit date |
|---|---|---|
3638c805ee
All checks were successful
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 58s
standards workspaces build + test / aac-rs (pull_request) Successful in 35s
standards workspaces build + test / joule-code-rs (pull_request) Successful in 47s
standards workspaces build + test / eoc-rs (pull_request) Successful in 1m48s
standards workspaces build + test / jcp-rs (pull_request) Successful in 1m14s
standards workspaces build + test / proof-rs (pull_request) Successful in 1m18s
standards workspaces build + test / jouleclaw-rs (pull_request) Successful in 3m37s
standards workspaces build + test / joulecontract-rs (pull_request) Successful in 43s
standards workspaces build + test / sandbox-rs (pull_request) Successful in 2m0s
standards workspaces build + test / map-rs (pull_request) Successful in 42s
standards workspaces build + test / mesh-rs (pull_request) Successful in 31s
standards workspaces build + test / smart-byte-rs (pull_request) Successful in 2m28s
standards workspaces build + test / openpay (pull_request) Successful in 1m47s
standards workspaces build + test / arl-rs (pull_request) Successful in 8m31s
standards workspaces build + test / joule-ui-rs (pull_request) Successful in 8m21s
standards workspaces build + test / jouledesk-rs (pull_request) Successful in 7m56s
standards workspaces build + test / joulehook-rs (pull_request) Successful in 8m24s
standards workspaces build + test / sense-rs (pull_request) Successful in 8m4s
`EedReport::is_compliant()` was `self.pue < 1.5 && self.renewable_pct >= 50.0`: two hardcoded floats with no provenance, no version, and no way to say which instrument they encode — the exact shape `BandingScale` was added to replace, sitting in the same crate, on the path a regulator would read. It also silently ignored water. `EedReport` has collected `water_usage_liters` all along, and the schemes that grade facilities grade on power **and** water, so the check discarded an axis it already had in hand. The test that demonstrates this is the reason for the deprecation rather than an argument for it: a facility with PUE 1.10 and 2.0 L/kWh **passes `is_compliant()` while its actual grade is F**. Three pieces: - `wue_milli_l_per_kwh()` derives Water Usage Effectiveness as an integer, and returns `None` rather than 0 when IT energy is zero. WUE is undefined there, and a 0 would read as *perfect* water efficiency for a facility that reported nothing — the flattering direction, which is the one to refuse. - `CompositeRating` combines several metric ratings into one published grade under a **declared** rule. "Worst of" and "mean of" are both defensible and give different letters for the same facility, so the rule travels with the grade for the same reason a `Rating` carries its scale. It keeps its components, so a reader sees *which axis set the grade* — a facility rated D on water with an A on power is a materially different thing from one rated D on both, and a bare letter cannot tell them apart. `binding_component()` names the axis an operator has to improve to move the letter, and `covers()` reports whether a required axis was graded at all, because a grade that silently omits one is not the scheme's grade. - `grade()` ties them together, taking the scales rather than embedding any. Which thresholds apply is the instrument's business, not this crate's — the same reason `BandingScale` still ships no canonical scale. `is_compliant` is deprecated rather than deleted: it is public API, and the deprecation note carries the reasoning to the call site, which a silent removal could not. Pre-existing tests that exercise it keep working under a module-level allow. Duplicate metrics are refused: the same axis graded twice votes twice, which under a worst-of rule is harmless and under any other rule is a silent weighting nobody declared. Found by the 2026-08-29 sweep, which flagged both that WUE was not rateable end-to-end and that this function had survived the change meant to retire it. Verified: 50 jouleclaw-compliance tests pass (7 new), no clippy warnings in the crate — the four reported are pre-existing, in jouleclaw-core and jouleclaw-energy. |
||
| .. | ||
| 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)