86e8619b71
JCP stops being only specified and starts being consumed. Three sibling standards now gate their real dispatch through Grants, the deterministic runtime, and sealed JCR-1 receipts — each via a small adapter crate with tests proving the gate: - jouleclaw-jcp: GatedTool wraps any jouleclaw-mcp MeteredTool so every MCP dispatch is decided against a signed delegation chain BEFORE a byte reaches the tool. The tool's stable id is the content-addressed resource (a same-named tool on another server is a different audience), the call's energy estimate is debited pre-dispatch, and every decision seals. Tests: a granted tool dispatches and debits; an ungranted tool named by a poisoned result NEVER runs (panicking stub proves it) and the refusal is sealed evidence; the budget stops a runaway loop at exactly the wall. - sandbox-jcp: JcpGate in front of Host::run_and_seal. The Grant binds to the unit's image BY CONTENT ADDRESS — one flipped image byte is a different audience, denied wrong-resource before the executor is ever invoked. The declared energy ceiling is debited from the chain pre-run (enforce before the side effect; energy never refunds), and a revoked grant goes dark. Two receipts per run: the JCP authorization + the sandbox's metered, attested execution, both JCR-1. - joule-code-jcp: GatedStage wraps any cascade Stage so every tier consultation is decided pre-dispatch — the tier is the action, the source tree the content-addressed resource, the tier's energy class the debit. Cheapest sufficient AND authorized: a grant that doesn't name l4 means the remote-frontier escape hatch never fires even when it would close the request; an exhausted budget stops it with a sealed budget-exceeded deny; receipts aggregate per-tier from evidence. Cross-standard path deps inside the monorepo (../../../../jcp/jcp-rs). Each adapter crate is tested in its own workspace; READMEs updated (jcp gains a "Consumers in this repository" section). Co-Authored-By: Claude Opus 4.8 <[email protected]>
86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
# 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](../openpay/), [Smart Byte](../smart-byte/),
|
|
[EOC](../eoc/), and [WAI](../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`](SPEC.md) | JouleClaw v1 spec — cascade tiers, energy contract, receipt |
|
|
| [`CHARTER.md`](CHARTER.md) | Stewardship pattern (shared across open-standards) |
|
|
| [`jouleclaw-rs/`](jouleclaw-rs/) | Apache-2.0 Rust reference implementation |
|
|
| [`spec/`](spec/) | Tier specifications, energy provenance, receipt format |
|
|
| [`conformance/v1/`](conformance/) | 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`](LICENSE))
|
|
- **Spec text:** CC-BY-4.0 (see [`spec/LICENSE`](spec/LICENSE))
|