| Filename | Latest commit message | Latest commit date |
|---|---|---|
6fe45b175f
The kernel adds a thread's CPU energy to its process's count (proc_pid_rusage ri_energy_nj) only when the thread leaves a core. A process reading its own count does not take the reading thread off its core, so the read is short of what that thread spent since it last left: a span's first read put up to a scheduling quantum of energy from before the span inside it, and its last read left the span's tail out. Both were sealed HwShunt. Measured against a reader that sleeps before its own reads and checks the process's context-switch count rose, 40 spans of each kind a run, three runs a host (macOS 27.0.1): - 1 ms of the reading thread's CPU: on an M5 Max at a load average of about 90, 25, 31 and 27 spans read no advance or under three quarters of the work; on an idle M3 Ultra, all 40 read no advance, every run; - a 2 ms sleep straight after 8 ms of CPU: on the M5 Max 25, 26 and 31 spans read the CPU before them as the sleep's energy, up to 18 mJ; on the M3 Ultra all 40 read the whole burn, 42 to 53 mJ for a sleep. ProcessCpuCounter now sleeps before each read of its own process (50 us, then 200 us, 1 ms, 5 ms) and reads only once the reading thread's own energy count (proc_pidinfo PROC_PIDTHREADCOUNTS, layout-gated: 88 bytes and two performance levels on both hosts) rose across a sleep. A read whose thread was not seen to leave is EnergyError::NotFolded, no reading: measure() gives no figure, read() fails, and a ProcessSpanMeter span falls back to the host meter. The fold is inside process::energy_nj, the one call span.rs makes for the CPU half, so it holds whatever order span.rs takes its readings in. The counter is Unavailable where the thread's count does not read, and the liveness probe still reads with no sleep. With it, all 40 spans of each kind agreed on both hosts: at least 95% of the work on the loaded M5 Max and 97% on the quiet M3 Ultra, at most 0.5% of the burn before a sleep; and under 40 busy loops on the M3 Ultra (220 runs), at least 84% and at most 2% (the oracle's window also holds both readers' own reads, which do not shrink with the work). A read costs about 80 us on the quiet M3 Ultra, about 200 to 330 us at the median under the busy loops, and 81 to 154 us at the median on the M5 Max at a load average of 135, against 1 us. tests/process_cpu_short_span.rs is the test that fails without the fold. Co-Authored-By: Claude Opus 5.5 <[email protected]> |
||
| .. | ||
| conformance/v1 | ||
| jouleclaw-rs | ||
| scales | ||
| vocab | ||
| LICENSE | ||
| LICENSE-SPEC | ||
| 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
LICENSE-SPEC)