| Filename | Latest commit message | Latest commit date |
|---|---|---|
b6ad1b0763
All checks were successful
jouleclaw fabrics / cuda (linux, RTX 4050 + Vulkan loader) (pull_request) Successful in 20s
jouleclaw fabrics / vulkan (linux, RTX 4050 + Vulkan loader) (pull_request) Successful in 20s
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 1m7s
joule-code conformance gate / Build + round-trip C1-C4 vectors (pull_request) Successful in 2m40s
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 1m39s
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 7s
joule-code conformance gate / joule-moq-ingest, every target (pull_request) Successful in 2m12s
joule-code conformance gate / joule-moq-relay, every target (pull_request) Successful in 2m32s
standards workspaces build + test / jouleclaw-rs (-nodebug, jouleclaw/jouleclaw-rs, -p jouleclaw-energy --features rapl,nvml, jouleclaw-rs, linux-arm64, -C target-feature=+fp16) (pull_request) Successful in 3m27s
standards workspaces build + test / joule-code-rs (joule-code/joule-code-rs, joule-code-rs, linux-arm64, true) (pull_request) Successful in 4m9s
standards workspaces build + test / mesh-rs (mesh/mesh-rs, -p mesh-engine-gguf -p mesh-openai --features mesh-engine-gguf/gguf,mesh-openai/server, mesh-rs, linux-arm64) (pull_request) Successful in 1m4s
jouleclaw fabrics / metal (macOS, Apple GPU) (pull_request) Successful in 58s
standards workspaces build + test / macOS energy backends (pull_request) Successful in 10m50s
standards workspaces build + test / jouledesk-rs (jouledesk/jouledesk-rs, jouledesk-rs, macos) (pull_request) Successful in 3m12s
#390 said the enforceable fix for `router_joules` was to give `RoutingPlan` a provenance, so a declared constant stops sharing a type with a measurement. This is that change. `RoutingPlan` gains `router_energy_class: Provenance`. Every router in this workspace sets `Estimator`, because every one of them charges a constant or a sum of constants — **nothing in routing is measured today**, and the type now says so rather than leaving a reader to find out. It matters because the figure is debited: `tier.rs` does `spent += plan.router_joules`, and a consumer that cannot tell a measurement from a constant cannot tell whether the budget it is enforcing means anything. Three alternatives were rejected on the merits, not on taste: - `JouleClass` is a tier taxonomy (Cache/Lawful/Embed/Model/Wire), not a grade. - Moving `Provenance` into `jouleclaw-core` would be the tidier home, but it has **61 importers**; churning them to serve two crates is not proportionate. - A local grade enum in cascade would make a third spelling of a vocabulary the family already has. So cascade and routing depend on `jouleclaw-energy` with `default-features = false`. Every hardware backend there is already opt-in, so this adds no meter to the cascade's dependency graph — just the type. **The magnitude is unchanged, deliberately.** `ROUTING_JOULES = 8e-9` J is 0.008 µJ: below the integer-microjoule unit the protocol uses (`EnergyReading` is `u64` µJ, and "floating-point is forbidden in the protocol for determinism"), so it rounds to zero there, and six orders of magnitude below the ~1 mJ floor `jouleclaw-energy` itself calls realistic for an `Estimator` source. The significand is unjustified. Correcting it needs a measurement; substituting a different invented number would repeat the error this change exists to label. Falsification found two real gaps in my own tests before this was right: - Mutating `LearnedRouter`'s and `PhasorRouter`'s own `RoutingPlan` literals changed **nothing**, because the test exercised `RoutingPlan::fallback` for both — their constructions were never reached. Fixed by driving each past cold start with `record_outcome` and asserting `!plan.is_fallback()` *first*, so the test cannot silently slide back onto the path that pins nothing. - Mutating `PrivacyRouter`'s composition to take the inner plan's class was **invisible**, because with every shipped router on `Estimator` the two expressions agree. Separating them needed a stub inner router claiming `HwShunt`, which pins the actual rule: a sum containing an unmeasured constant is an estimate, however good the measured term was. All four mutations now fail exactly one named test each. Lockfiles: both workspaces that name these crates are refreshed (`jouleclaw/jouleclaw-rs`, `joule-code/examples/l3-jouleclaw`); 47 lockfiles current. Verified: workspace check 0 errors, 486 test binaries green, 0 failures; `l3-jouleclaw` check 0 errors. The 10 clippy findings in these crates are pre-existing, unchanged in count, and all in lines this change did not author (`coord_router_impl.rs:241` shifted to `:242` behind an inserted line); neither crate is in CI's clippy list. Co-Authored-By: Claude Opus 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)