| Filename | Latest commit message | Latest commit date |
|---|---|---|
50ec5d3339
All checks were successful
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 1m9s
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 9s
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 2m22s
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 1m3s
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 2m20s
standards workspaces build + test / macOS energy backends (pull_request) Successful in 7m55s
standards workspaces build + test / jouledesk-rs (jouledesk/jouledesk-rs, jouledesk-rs, macos) (pull_request) Successful in 2m39s
The parser read the wrong bytes for most of the fields it emits. Its test fixtures were built from the same constants, so nothing could catch it: TDX: - The header is 48 bytes, not 52; qe_vendor_id sits at byte 12. - The TD 1.0 report body is 584 bytes, not 528. - mrtd is at body+136, not body+0, which is TEE_TCB_SVN and MRSEAM. - rtmr0..3 are at body+328/376/424/472, not 168/216/264/312. - report_data is at body+520, not body+376, which is RTMR1. - A v5 quote is not "backward-compatible on the header fields": a 6-byte body descriptor (type, size) comes before its body. SNP: - The launch measurement is at 0x090, not 0x130, which lies inside author_key_digest. - id_key_digest is at 0x0E0, not 0x160, which is report_id_ma. - report_data at 0x050 and host_data at 0x0C0 were already right. Every offset is the one sandbox-tee's verifier uses, and agrees with the published layouts. The parser now also refuses a quote whose tee_type is not TDX (0x81), and a v5 quote whose body is not a TD report (type 2, 584 bytes, or type 3, 648 bytes, with a matching size), rather than reading them at TD offsets. The fixtures are rewritten from literal published offsets, independent of the parser's constants. Every field gets its own marker, with decoys at the offsets that were read before. The vec_init_then_push pattern and a module-doc list item that clippy flagged are fixed in the same functions; the doc no longer claims a tcb_svn field it never emitted. No crate in the tree depends on this one, so the defect was latent. Tests: 12. Mutation testing: 13 mutants, all killed. Six put back an old offset, which is exactly the code this replaces. The other seven remove the tee-type check, the v5 descriptor and size checks, the TD 1.5 length, v5 support, or the short-body check. Verified on the build host: clippy -D warnings and rustdoc -D warnings clean on jouleclaw-attest-vendor. 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)