| Filename | Latest commit message | Latest commit date |
|---|---|---|
7c44d332e3
All checks were successful
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 7s
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 59s
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 1m31s
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 4m11s
jouleclaw public surface must stay documented / Public-surface audit (jouleclaw-rs) (pull_request) Successful in 1m15s
standards workspaces build + test / macOS energy backends (pull_request) Successful in 13m14s
standards workspaces build + test / jouledesk-rs (jouledesk/jouledesk-rs, jouledesk-rs, macos) (pull_request) Successful in 4m23s
`compose_verified_answer` built each segment's `ClaimAttribution` from
ds.cited_item_ids.iter().filter_map(resolve).next()
under a comment reading "Source URI from the most authoritative cited item".
`.next()` is the first cited id that happens to resolve, in whatever order the
ids were listed — a stated selection criterion the code did not perform.
Authority tier 1 is `AuthorityTier::Primary` and 4 is `Community`, so the most
authoritative cited item is the **minimum** tier. A segment citing a forum post
before a peer-reviewed source was therefore attributed to the forum post, and
the whole attribution rides on that one choice: `retrieval_source_uri`,
`retrieval_timestamp` and `retrieval_axes` all come from it. Selection is now
`min_by_key` on the tier, with ties broken on `item_id` so the result is
reproducible rather than a function of citation order.
A second problem sat in the same expression. `filter_map` drops a cited id that
matches no retrieved item **silently**, so a segment whose citations all dangle
came out with the ids still attached and an all-`None` attribution, with
nothing anywhere stating why. A reader sees citations and no source. Dangling
citations are now counted and reported as a caveat, using the mechanism the
function already uses for dropped segments. This is the honest shape of the
problem the sweep called "citation laundering": the citations are not read back
as provenance, and the gap was invisible.
Three tests, each pinning one property, every one of them discriminating on
*order* rather than on a single arrangement:
- the same two items, tier 1 and tier 4, cited both ways round, must attribute
to the tier-1 source both times;
- two items of **equal** authority, cited both ways round, must resolve the
same way — the tie-break is the only thing that makes this true, and it is
the only test that catches its removal;
- a segment with one real and one dangling citation reports the dangling one
and still attributes from the real one; a segment where every citation
dangles has no attribution at all, which is when saying so matters most.
The sweep's own description of this finding was wrong in its specifics —
`cited_item_ids` is read in three places, and there is no `jouleclaw-diagnose`
crate — but reading the code to check surfaced the real defect beside it.
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)