| Filename | Latest commit message | Latest commit date |
|---|---|---|
08b5db2c23
All checks were successful
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 1m58s
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 19s
standards workspaces build + test / macOS energy backends (pull_request) Has been skipped
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 56s
standards workspaces build + test / joulehook-rs (joulehook/joulehook-rs, joulehook-rs, linux) (pull_request) Successful in 1m15s
The GGUF-crate engines (Gemma and Falcon-H1) reported no `weights_digest` and no `precision`. A receipt from a real model therefore bound it by recipe name alone, and #294's routing gave a grant's `ModelIn` caveat nothing to match. A grant that named the model it permitted refused every real backend. The engine itself recorded the intended fix: address the weights once, at load, over every byte, and report nothing rather than a partial digest. - `mesh_engine::weights_digest(dir, files)` is the shared rule (SPEC §3.6). It is BLAKE3 over the canonical list of the files the forward pass reads. Each file is named by its path relative to the model directory and addressed by the streamed BLAKE3 of all its bytes, in path order. File names are part of the address, and listing order is not. - `GgufEngine` addresses `config.json` plus `model.safetensors`, or the index plus every shard it names. A shard the index names but the directory lacks is an error. It reports `fp32`: the loader widens every tensor to f32. - `FalconEngine` addresses `config.json` plus `model.safetensors`. The tokenizer is not addressed, because it maps text to the ids a caller sends and does not reach the forward pass. It reports `bf16`, the only dtype it binds. - Both report the digest before serving (`ServingEngine::weights_digest`) and the same digest after, which is what mesh-core's model check requires. - SPEC §3.6 states the rule. Checked on the build host: - mesh-rs: 79 tests pass. mesh-engine-gguf's synthetic-directory test runs under the gguf feature, as CI's mesh-rs leg builds it. - On real weights, a sharded 12B Gemma directory (config, index and three shards) addresses exactly the files on disk. It took 8.5 minutes from the host's external disk; at load the loader has just read the same bytes, so they normally come from the page cache. - Every Cargo.lock is current, including joulehook-rs, which locks mesh-engine. Clippy is clean. - Mutations each fail tests: names left out of the manifest, hashing only a file's head, and skipping the index's shards. Co-Authored-By: Claude Opus 5.5 <[email protected]> |
||
| .. | ||
| conformance/v1 | ||
| joulehook-rs | ||
| LICENSE | ||
| LICENSE-SPEC | ||
| README.md | ||
| SPEC.md | ||
JouleHook — Metered, Gated, Attested Agent Work in Any Host
Provisional name — the steward may rename; the profile string joulehook/1 and the
seam names are the stable surface.
The energy-accounting and methodology-gating you build for one coding agent is worth little if it's trapped in that one agent. JouleHook carries it into the editors developers already use — Claude Code, Cursor, Windsurf, Antigravity, Zed, JetBrains, OpenCode — without forking any of them.
It rests on one finding: no host lets an extension observe its agent's tokens or intercept its native tools — but every host exposes the same three seams, and JouleHook is the normative contract over them:
A per-action gate, a model-call meter, and a receipt surface. Bind those three to a decide-outside-the-model grant check, an honest energy meter, and a sealed receipt, and any agent's work becomes a metered, gated transaction — from one core.
JouleHook does not replace the host's agent. It is the host-binding layer for the
sibling standards: JCP decides and grants, Mesh meters at the model front
door, jcp-efficiency is the receipt. JouleHook adds the seam contract and the
per-host conformance profiles that make them portable.
- Licence: Apache-2.0 for reference code (
LICENSE); CC-BY-4.0 for specification text (LICENSE-SPEC). - Status: v0.1.0 draft. Specification published (
SPEC.md); reference workspacejoulehook-rs/ships the gate binding (joulehook-hook) for theclaude-codeandhooks-familyprofiles — one PreToolUse hook that gates by JCP capability (decided outside the model, every decision sealed) and speaks the native decision format of Claude Code, Cursor, Windsurf, and Antigravity behind a--hostselector;joulehook-statusline, the in-editor joule meter (honestestfrom Claude Code's own tokens); andjoulehook-mcp, an MCP server that surfaces the sealed decisions as verified, human-readable resources in any MCP-speaking editor. Theclaude-codefullprofile installs today (joulehook-rs/INSTALL.md); the enforcing Mesh-proxy meter + a site land next.
The three seams
| Seam | Host mechanisms | What rides it |
|---|---|---|
| Gate | PreToolUse-hook family; ACP request_permission |
allow / deny / rewrite, decided outside the model, sealed |
| Meter | base_url proxy; OTel gen_ai.* |
tokens→joules, honest provenance, enforceable joule ceiling |
| Receipt | MCP resources; status line; panel | hash-chained, verifiable efficiency/1 + decision receipts |
Conformance profiles
claude-code (reference) · hooks-family (Cursor / Windsurf / Antigravity) · acp
(Zed / JetBrains / Neovim) · opencode · cline · vscode (Open-VSX) · meter-only
(Continue, any OTel host). See SPEC.md §6.
The honest limit
A host-side adapter alone cannot meter the host agent's own tokens; a complete energy
figure requires the Meter seam (proxy or OTel). An adapter that claims whole-session
energy without a bound meter is non-conformant (SPEC.md §7).
What's here
joulehook/
├── SPEC.md — the normative standard (§1–§9)
├── README.md — this file
├── joulehook-rs/ — reference implementation
│ └── crates/
│ ├── joulehook-hook — ✅ the PreToolUse gate CLI for the hook family
│ │ (Claude Code / Cursor / Windsurf / Antigravity via --host;
│ │ wraps jcp-bridge::LocalToolGate for the JCP check + seal)
│ │ + joulehook-statusline — ✅ the in-editor joule meter
│ ├── joulehook-mcp — ✅ the receipt-surface MCP server (sealed decisions →
│ │ verified MCP resources, any MCP-speaking editor)
│ ├── joulehook-meter — ✅ the meter-seam binding: inject a grant's budget as
│ │ the Mesh joule ceiling (enforce) + bridge Mesh's
│ │ usage.energy into an efficiency/1 receipt
│ └── joulehook-proxy — ✅ the deployable meter: an OpenAI-shaped base_url
│ proxy that caps + seals every model call
└── conformance/v1/ — ✅ reproducible vectors: per-host decision encodings
(decisions.json) + a byte-deterministic sealed deny receipt
(deny-receipt.hex + receipt.json, verified-decode)
JouleHook is one of the Transaction Science open standards. Transaction Science is the steward, not the proprietor.