Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 16 Packages Wiki Activity Actions 141
open-standards/jouleclaw
History
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Transaction Science b2e75b9f37 jouleclaw-energy's process-counter test kills and reaps its busy child, however the test ends 
tests/process_cpu.rs (macOS) starts a child that spins `while :; do :; done` and kills it
inside the window it meters. Between its spawn and that kill each energy read asserts; a read
that failed there unwound past a bare std::process::Child, which is not killed when it is
dropped, and left the child spinning a core once the test binary had ended, one more for each
failed run. The child is now held, as it is spawned, in a `Running` that kills it and reaps it
when it is dropped, waiting up to 10 s (as wai-quantum-service's tests hold theirs, 04d19cfd8);
the test still kills and reaps it inside the window, so what it meters is unchanged.

Planted fault, on the old-prod Mac Studio (macOS, M3 Ultra): the test made to panic right
after its first read of the child's counter, with the child running, run alone in a session and
process group of its own (POSIX setsid; macOS has no setsid command, and its ps and pgrep
cannot select by session, so the group was listed), 3 s after cargo ended. At main the group
held the busy child (/bin/sh -c while :; do :; done, 3 s old), which was then killed by its
group; with the guard it held nothing.

Gates, on the old-prod Mac Studio: cargo test --locked -p jouleclaw-energy passed (76 tests in
9 binaries) and with --features ioreport (144 in 9), each leaving nothing in its process group;
cargo clippy --locked --all-targets --no-deps -p jouleclaw-energy -- -D warnings is clean in
the default build and with ioreport. The light checks pass.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-10 12:35:59 -05:00
..
conformance/v1 jouleclaw SPEC.md: normative §§8-12 for waves 12-21 2026-06-02 10:42:25 -04:00
jouleclaw-rs jouleclaw-energy's process-counter test kills and reaps its busy child, however the test ends 2026-11-10 12:35:59 -05:00
scales compliance: publish the EU draft PUE bands as a sourced data pack, not as code 2026-09-06 06:24:25 -04:00
vocab jouleclaw: wave-24 — contract + handoff + mission + value report 2026-06-03 02:35:34 -04:00
LICENSE jouleclaw: standard skeleton + Phase 1 foundation crates 2026-05-26 09:55:11 -04:00
LICENSE-SPEC licences: ship the Apache-2.0 text the code already declares 2026-10-09 17:22:32 -04:00
README.md licences: ship the Apache-2.0 text the code already declares 2026-10-09 17:22:32 -04:00
ROADMAP.md docs: strip vanity metrics from README + ROADMAP 2026-06-02 07:30:50 -04:00
SPEC.md Every text that states the IOReport liveness rule states it as the meters apply it 2026-11-07 08:20:02 -05:00

README.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