| Filename | Latest commit message | Latest commit date |
|---|---|---|
35b7bd3972
All checks were successful
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 1m25s
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 5s
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 36s
standards workspaces build + test / macOS energy backends (pull_request) Successful in 6m56s
standards workspaces build + test / jouledesk-rs (jouledesk/jouledesk-rs, jouledesk-rs, macos) (pull_request) Successful in 2m34s
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 59s
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 2m49s
A JouleClaw run journal recorded a node only when it completed
(`NodeRecorded`). Nothing recorded that a node had begun. A process that
died in the middle of a node therefore left no trace of it, and a
restarted run found the node ready again. The next dispatch repeated
whatever it had done outside the run (a message sent, a payment made, a
record written) with no sign it might already have happened, and the
interrupted attempt's energy was lost. JCP §4.11 requires the decision
to be recorded before the action runs and forbids silently retrying one
whose outcome is unknown. jcp-orchestrate, mesh and jcp/1 already do
this; the run journal did not.
A comparison with durable agent harnesses prompted this. The common shape
commits a tool call's intent before running it, reruns calls declared
safe, and tells the model an unsafe one may have partly run. Published
crash tests of that default show its weakness: a model retried an
interrupted write it could not see and left a duplicate. Here an
interrupted `never` node is not left to a model: it is held until someone
settles it.
- **Rule and events.** `Replay { Safe, Never }`, with `Never` the
default. New `RunEvent`s: `NodeDispatched { attempt, replay }`,
written before work begins; `NodeInterrupted { attempt, observed_uj }`;
and `RerunApproved { approved_by }`. The rule travels with the
dispatch, not on `Node`, so every graph's content address and every
persisted journal are unchanged.
- **`Run::dispatch`** records the dispatch and returns the attempt. A
node in flight is not ready, so it is not dispatched twice.
- **`Run::recover`** marks every node still in flight after a restart as
interrupted, keeping the energy observed for the attempt as a lower
bound. An interrupted `Safe` node is ready again as a new attempt. A
`Never` node is held (`held_nodes`) until it is recorded, approved for
a rerun by a named party (`approve_rerun`), or the run fails.
- **Fail-safe.** A consumer that omits `recover` leaves the node in
flight and out of `ready_nodes`, so it stalls rather than repeats.
`record` without a prior `dispatch` works as before, so existing
consumers are unaffected.
- **jouleclaw-stuck** counts dispatch, interruption and approval
timestamps as activity, so a run whose last event is a long node's
dispatch is not reported abandoned.
- **Spec.** JouleClaw SPEC §17.3 states it.
Checked on the build host:
- jouleclaw-graph: 47 tests pass, six of them new. jouleclaw-stuck: 17,
one new.
- jouleclaw-gate, graph-mcp, mission, artifact, reflection and promote
pass, and the JouleClaw workspace checks. Clippy is clean.
- Mutations each fail tests: ready_nodes ignoring in-flight and held
nodes, dispatch ignoring a held node, every interrupted node rerunnable,
interrupted energy dropped, and stuck ignoring dispatch.
Not in this change: jouleclaw-mission dispatches features rather than
graph nodes and has no resume of its own. Wiring its workers through
`dispatch` / `recover` is the next step.
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)