| Filename | Latest commit message | Latest commit date |
|---|---|---|
3b1b3ff235
All checks were successful
standards workspaces build + test / jouleclaw-rs (pull_request) Successful in 2m48s
standards workspaces build + test / aac-rs (pull_request) Successful in 1m0s
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 57s
no-vanity-metrics / Scan committed Markdown for vanity metrics (pull_request) Successful in 3s
no-vanity-metrics / WAI public text names no comparison (pull_request) Successful in 3s
no-vanity-metrics / WAI public text names no company or product (pull_request) Successful in 3s
standards workspaces build + test / joule-code-rs (pull_request) Successful in 56s
standards workspaces build + test / arl-rs (pull_request) Successful in 1m7s
standards workspaces build + test / joulecontract-rs (pull_request) Successful in 35s
standards workspaces build + test / map-rs (pull_request) Successful in 31s
standards workspaces build + test / mesh-rs (pull_request) Successful in 25s
standards workspaces build + test / eoc-rs (pull_request) Successful in 1m53s
standards workspaces build + test / openpay (pull_request) Successful in 1m33s
standards workspaces build + test / jcp-rs (pull_request) Successful in 1m27s
standards workspaces build + test / joule-ui-rs (pull_request) Successful in 1m8s
standards workspaces build + test / joulehook-rs (pull_request) Successful in 1m14s
standards workspaces build + test / proof-rs (pull_request) Successful in 1m18s
standards workspaces build + test / sandbox-rs (pull_request) Successful in 2m21s
standards workspaces build + test / sense-rs (pull_request) Successful in 1m5s
standards workspaces build + test / smart-byte-rs (pull_request) Successful in 3m37s
standards workspaces build + test / jouledesk-rs (pull_request) Successful in 3m56s
standards workspaces build + test / macOS energy backends (pull_request) Successful in 8m44s
Two problems, and they were the same problem seen from either end. The crate's own promise is that "any party can prove a receipt was included in the log without trusting the log operator". An inclusion proof delivers that only against a root the operator is bound to, and `TreeHead` — documented as a "Signed Tree Head" — had no signature, no key, and no verification. An unsigned root can be minted per-auditor, so two parties shown different roots had nothing to compare and nobody to attribute it to. The promise was false as written. And nothing consumed the crate. The RFC 6962 proofs merged in #153 were inert: no JouleClaw or JCP decision could be given an inclusion proof, so the auditor-grade tier existed as an unreferenced library. **Signed tree head.** `TreeHead::sign` / `SignedTreeHead::verify` over `0x02 || size || root || timestamp`, every field fixed-width so no two heads share a preimage, and `0x02` a third domain separator so a head cannot be presented as an entry in its own log. `verify` returns the *root* rather than `()`, so a caller cannot check a proof against an unverified head by accident. `root_hex` is a `String`, so it is now parsed rather than assumed: a head whose root is not 32 bytes of hex is refused at signing time and again at verify time, because a signature over an unparseable root is a signature over nothing checkable. Tests cover each field being load-bearing, the wrong key, malformed signature bytes, and — the property an unsigned root cannot have — two signed heads at one size as attributable equivocation. **A consumer.** `JcpGate` already accumulated its sealed receipts in a private `Vec`, which is only as trustworthy as the party holding it. Each receipt is now appended to a Merkle log on the same path, and the gate publishes `signed_tree_head`, `inclusion_proof` and `consistency_proof`. An auditor with only the steward's public key can check that a specific decision — allow or deny — is in the stream the operator published. Stream and log are appended in one place so an index into one is an index into the other. **Fail closed.** On that path, `if let Ok(receipt) = seal_chained(..)` swallowed a seal failure and then returned the verdict, so an *allow* could proceed with no receipt and no log entry — the one outcome the log exists to make impossible. A seal failure now refuses the dispatch. The debit has already landed, so the caller is charged for a call it does not get; that is the safe direction, because the opposite is an unrecorded side effect. **What this does not prove**, stated in the module docs and the spec rather than left to be inferred: not completeness. An operator that never records a decision logs nothing, and no proof about the entries that exist can speak for one never written. What narrows the gap is where the append happens — before the verdict returns, so a caller that observed a refusal can demand the entry that refused it. SPEC gains §22 (Transparency log, OPTIONAL): the tree, the signing preimage byte-for-byte, the MUSTs on signing and on refusing an unparseable root, the proven/not-proven split in plain terms, and conformance class C-TLOG. References moves to §23; nothing cross-referenced it. Co-Authored-By: Claude Opus 5 <[email protected]> |
||
| .. | ||
| conformance/v1 | ||
| jouleclaw-rs | ||
| scales | ||
| 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)