| Filename | Latest commit message | Latest commit date |
|---|---|---|
ad8fbf48ca
On macOS 27.0.1 an unprivileged reader sees the machine-wide IOReport CPU rail frozen, so every meter here has been an estimator on Apple Silicon. The kernel does keep a live per-process figure: `proc_pid_rusage(getpid(), RUSAGE_INFO_V6)` and its `ri_energy_nj`, the CPU energy it attributes to this process's threads, public libproc, no privilege. On this M5 Max it advances every few milliseconds under load. Its coverage is the trap. It counts this process's own threads and nothing else: not child processes (the kernel never folds a child's energy into its parent, not even after reaping it; `rusage_info` has a child CPU-time field and no child energy field), not other processes, not the GPU or the ANE. `PowerMeter` meters subprocess work in jcp-gateway (the upstream MCP server), joule-code-remediate (cargo) and sandbox-proof (the engine), and in-process work in joule-ui-serve's handlers. A probe added to `detect()` would read the gateway waiting, near zero, as the energy of the tool call. So the new `ProcessEnergyProbe` (`Cpu`, `HwShunt`, source "process-energy") is never part of `detect()`. It is reached only through a new constructor, `PowerMeter::detect_in_process()`, documented as only for work on this process's own threads: where the counter is live the meter reads it and nothing else (a machine-wide CPU probe beside it would count the same work twice); where it is not, and off macOS, it is `detect()`. The counter is gated by the shared rule, probed once per process and cached (`process_energy_status()`, a `CounterStatus`): it must advance in at least five intervals, at least four in five, over at least 300 ms, while the probe burns CPU, through the same `liveness::counter_run` and `gated` as RAPL and NVML. `Span::stop`'s held-CPU rule applies unchanged: a span over which the counter did not advance is estimated. The struct is the SDK's `rusage_info_v6` field for field, pinned by a test at the SDK's own sizeof and offsets (464 bytes, `ri_energy_nj` at 336). `run_attributed` (subprocess windows). The question was whether a child's own figure can be read reliably. It can, for the direct child: wait for the exit without reaping (`waitid(P_PID, pid, WEXITED | WNOWAIT)`), `proc_pid_rusage` the exited child, then reap with `wait4` as before. Measured here before writing it: the read succeeds on the zombie and is stable across repeated reads, then fails (ESRCH) once reaped; `sh -c 'awk ...'` (sh execs awk) read 1.647 J for 0.6 s of awk's CPU; `sh -c 'awk ...; true'` (awk a reaped child of sh) read 5.5 mJ, sh's own start-up, beside 0.63 s of reaped-descendant CPU time. So the new `Attribution::child_energy_uj` is the direct child's own energy, given only when the per-process counter is live, the child reaped no descendant that used CPU time, and it advanced. Grandchildren are not covered: cargo -> rustc gets `None`, as does any shell that forks its commands, and a descendant the child did not reap leaves no trace at all. The status is read before the window opens, so its first-use probe never lands inside it. The apportioned `attributed_uj` is unchanged. jcp-gateway, joule-code-remediate and sandbox-proof stay on `detect()`, and their docs now say why: their metered work is a subprocess. remediate's test helper sets the new field to `None` (cargo). Tests. Hardware, in their own process (`tests/process_energy.rs`, one at a time, each against an oracle that reads `ri_energy_nj` into a raw buffer at the SDK offset and shares no code with the probe): `the_process_energy_probe_is_live` (pinned Live on Apple Silicon; the oracle saw 39/39 intervals advance; the probe ran once), `an_in_process_burn_is_a_hardware_reading_of_its_energy` (200 ms of one thread's CPU, user-interactive QoS, via `detect_in_process`: one `Cpu` `HwShunt` record in 0.2..20 J and inside the oracle's reading around it), `an_in_process_sleep_reads_under_a_tenth_of_a_joule`, `detect_does_not_include_the_process_probe`, `work_in_a_child_process_is_not_attributed_to_the_in_process_probe`. Unit: `the_rusage_struct_is_the_sdks_layout`, `this_process_reads_itself_and_a_missing_pid_reads_nothing`, `a_childs_own_energy_is_a_reading_only_for_a_single_process_child`, `only_a_live_status_builds_the_process_probe`, `detect_never_reads_this_process_counter` (every status combination), `detect_in_process_reads_this_process_only_for_a_live_status` (and never calls the fallback when it reads), `a_single_process_childs_own_energy_is_read_before_it_is_reaped`, `a_child_whose_work_ran_in_a_descendant_has_no_reading`. Measured on this M5 Max (macOS 27.0.1, other builds loading it), verbatim: 200 ms in-process burn: 0.4361 J over 219.588375ms wall (oracle around it: 0.4361 J) 200 ms in-process sleep: 575 µJ child work: child 0.8730 J, this process 0.001304 J around the wait, span [... measured_uj: Some(1304) ... HwShunt] process energy: status=Live oracle advanced in 39/39 intervals, probe runs=1 child energy: status=Live child_energy_uj=Some(3128510) proc_cpu_secs=1.499 On the M3 Ultra (macOS 27.0.1, 10.10.10.2; lib and process_energy test binaries copied, run once with --nocapture, deleted), verbatim: 200 ms in-process burn: 1.3150 J over 200.032666ms wall (oracle around it: 1.3150 J) 200 ms in-process sleep: 1796 µJ process energy: status=Live oracle advanced in 40/40 intervals, probe runs=1 child work: child 2.3750 J, this process 0.014451 J around the wait, span [... measured_uj: Some(14451) ... HwShunt] child energy: status=Live child_energy_uj=Some(10145217) proc_cpu_secs=2.044 ioreport liveness: status=CpuRailFrozen oracle=CpuRailMoved(false) selected=false 105 lib tests and 5 process_energy tests passed. The per-process counter is live on both chips; IOReport's CPU rail stays frozen. sandbox-meter passes (105 lib, 5 process_energy, both once-per-process files); every sandbox-rs crate that depends on the meter passes (238 tests); jcp-gateway and jcp-action-receipt (33) and joule-code-remediate (13) pass. Clippy is clean for aarch64-apple-darwin and x86_64-unknown-linux-gnu, and x86_64-apple-darwin checks clean. Falsified, each restored from git and re-run green: the probe added to `detect()` fails `detect_never_reads_this_process_counter` and `detect_does_not_include_the_process_probe`; a constant counter, and the parent's pid in place of this one, fail `the_process_energy_probe_is_live` (status Frozen while the oracle saw it advance) and the 200 ms burn (it falls back to the 4.1 J estimate); `given` ignoring the status fails `only_a_live_status_builds_the_process_probe` and `detect_in_process_reads_this_process_only_for_a_live_status`; a child reading that ignores reaped descendants fails both child tests (sh's 5.5 mJ stood in for awk's work); one that ignores liveness fails the pure child test. Rebased onto |
||
| .. | ||
| conformance | ||
| examples | ||
| joule-code-rs | ||
| spec | ||
| vocab | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| LICENSE-SPEC | ||
| README.md | ||
| ROADMAP.md | ||
| SPEC.md | ||
Joule Code
A carrier for coding work. Federated, energy-attributed, owned by no one.
Joule Code is the coding cargo class of the Transaction Science substrate. Where Smart Byte carries value, EOC carries compute, and Ambient Mobile (CommunicationOS) carries signal, Joule Code carries agentic coding operations — an edit, a refactor, a generated function, a review — as a content-addressed, signed transition with its energy cost intrinsic.
A coding operation is not a chat turn and not an opaque API call. It is a vesicle carrying exactly five things: identity (the blake3 content address of its canonical serialization), provenance (the prior tree state it builds on, and the author key that authorized it), an ownership chain (signature-bound transitions, so a change cannot be replayed onto a different base), cargo (the change itself — an edit set against a tree), and a two-part joule cost (measured + estimated, with an honest provenance tag on every reading). Operations resolve through an explicit energy-tiered cascade — cache, then deterministic, then retrieval, then a local model, then a remote frontier agent as the last resort — and stop at the first tier that closes the request. Inference is the escape hatch, not the entry point.
The substrate is intentionally ownerless: no protocol-level token, permissive licensing on the spec text and reference code, and conformance test vectors so any implementer can verify canonicity without a trust relationship with the authors. A conforming Joule Code endpoint drives a vendor's own logged-in coding agent (the vendor CLI owns its token; the protocol never sees a credential), measures the energy of every operation, and emits a signed receipt — with no contact with any single company's servers as a condition of operation. Transaction Science is one steward: it publishes the spec, ships a reference implementation, and operates commercial services around the substrate — not its proprietor.
The doctrine
Capability per joule, not capability per token. The durable layer of a coding tool is not token resale or editor convenience — both are commoditized. It is the substrate, measured in joules per accepted change. "Make it work" and "don't waste energy" are the same optimization: thrash is simultaneously the bug and the energy leak.
Three consequences, normative in SPEC.md:
- The cascade. Every coding request dispatches through
L0:Cache → L1:Lawful → L2:Embed → L3:Model → L4:Wireand stops at the first tier that closes it. The agent schema is JouleClaw; the remote frontier agents (Claude Code, Gemini, Codex, ...) are L4, reached over the Agent Client Protocol (ACP). - The receipt. Every operation reports a two-part energy cost in microjoules —
measured + estimated— with aProvenancetag (HwShunt | ModelBased | Estimator) on every reading, sealed as a JCR-1 envelope (canonical det-CBOR + COSE_Sign1/EdDSA — the family's shared signed-receipt format). The spec never claims an accuracy the platform cannot deliver. - No capture. No protocol token. The credential to a frontier agent lives in the vendor's own CLI, never in the protocol. A conforming endpoint performs its core function without phoning home to any single company.
Contents
SPEC.md— the normative specification (RFC 2119). The coding-operation cargo, the cascade binding, the receipt schema, and the conformance contract.spec/— sub-specifications: the coding-operation cargo type, the cascade binding, the receipt format, and the federated collaboration binding.vocab/— the controlled vocabulary (LEXICON.md).conformance/— signed wire vectors. A standard is conformant if it round-trips these.joule-code-rs/— the Rust reference library: the protocol crates (schema, cargo, receipt, cascade, conformance), plusjoule-code-jcp— the cascade as a JCP consumer: every stage consultation is decided by the JCP runtime against a metered Grant before the stage runs (the tier is the action, the source tree the content-addressed resource, the tier's energy class the debit), so the L4 escape hatch to a remote frontier agent exists only when a signed grant names it and can pay for it. Every consultation, allowed and denied, seals as a JCR-1 receipt.joule-code-joulecontractbinds an operation to the sibling JouleContract standard: the edit set is the contract's frame (an out-of-frame edit is caught at the boundary and recorded, not suppressed), the tier cost is the ceiling, and JCR provenance maps downward-only onto the energy classes (Estimatorcan never serialize asMetered).joule-code-remediateis the reference verified-fix harness (joule-fix): it scans a Rust workspace, remediates at the cheapest sufficient tier (L1 lawful codemods first — deterministic, zero inference), and gates every fix behind a pipeline whose stages ARE the contract's obligations — baseline capture, build, no-new-test-failures, lint-delta, frame confinement, diff guard — each discharged with its actual outcome. A fix that fails any gate is reverted and never ships, and the refusal itself produces a receipt. The run's energy is measured by the sibling sandbox standard's hardware meter and sealed as a JCR-1 envelope that serves as the JouleContract receipt's meter attestation — one standard's receipt is the other's evidence — and the harness reports energy per verified fix from hardware counters, not estimates. A methodology layer makes spec-driven development auditable on top of the protocol:joule-code-specis the signed, content-addressed Spec — intent plus individually addressable clauses (requirements, constraints, and first-class non-goals), with a signed Citation binding each operation to the clauses it implements and a deterministic coverage audit that names open obligations and flags any cited non-goal.joule-code-reviewmakes two-stage review (spec-compliance, then quality) a signed artifact where separation of duties is a signature check: a review whose reviewer key equals the operation's author key is structurally void — self-review cannot stand, human or agent.joule-code-revieweris the independent reviewer agent that produces those reviews — a distinct principal making a real, falsifiable judgment (it refuses to review its own work, and it can request changes), arranged as a cheapest-sufficient cascade: a learned tier (defect patterns a model has already taught it, applied model-free), a structural tier, and an optional semantic model tier behind a subprocess seam. The model's rejections compile into learned skills so a recurring defect is caught for nanojoules — the fix harness's amortization moat, applied to review — while approvals are never cached, because a stale approval is a silent-failure lane.joule-code-releaseis the total door: a release certifies only when all four gates — spec coverage, contract discharge, two-stage review, attested build — are present and satisfied, and otherwise refuses with the missing gate named. Two terminal states, no third. This is the lean library a third party implements against — not an editor.
Reference implementation and consumers
joule-code-rs/ is the protocol library. The flagship consumer is a hard fork of the Zed editor ("agent-zed"), which drives logged-in vendor coding agents over ACP, meters every turn, and surfaces the joule receipt in its UI — the SOTA editor surface for the standard. The protocol is what any party implements; the editor is one (high-quality) consumer, the way wai-rs is the standard and CommunicationOS is a consumer.
Status
v0.2.0 draft. Specification core published (cargo, cascade binding, receipt); reference library lands the schema, cargo, receipt, and cascade crates with a conformance harness. Receipts seal as JCR-1 envelopes (canonical det-CBOR + COSE_Sign1, EdDSA), the signed-receipt format shared across the family, so a Joule Code receipt verifies under existing JCR-1 tooling. The conformance vectors are real, cryptographically computed values (the harness passes the whole pack with no skips). The federated-collaboration binding is Research and is specified at the interface level only — single-endpoint operation is the current surface.
Readiness is classified per component (Solid / Engineering / Research / Theory) in SPEC.md §9 and respected when sequencing work.
Related
- JouleClaw — the energy-optimised AI runtime; Joule Code's agent schema. The cascade tiers and the receipt provenance discipline are JouleClaw's.
- Smart Byte — the value carrier; a Joule Code operation is structurally a Smart Byte whose cargo is a code change. Identity, signing, and lockstep replication are shared.
- EOC — the energy-optimised compute substrate; the cheap cascade tiers (cache / retrieval) follow EOC's resolution discipline.
- CommunicationOS — the signal carrier; the federated-collaboration binding transports coding operations between collaborators over its group-state and media paths.
Licence
Reference code (everything under joule-code-rs/) is Apache-2.0 (LICENSE). Specification text (SPEC.md, spec/, vocab/) is CC-BY-4.0 (LICENSE-SPEC). The wire format and the right to fork are public.