The promise is the artifact.
The code is the byproduct.
JouleContract is an open standard for energy-accounted interface contracts: five clauses — what must hold, what may be touched, what may be spent — discharged into one signed receipt that evidences safety, energy, and governance at once. Every trust-bearing field binds to a key, a sealed attestation, or an independent timestamp, or it is recorded as untrusted.
The core object
Five obligations, content-addressed.
A JouleContract is the noun the rest of the family acts on: Joule Code carries its changes, the proof standard discharges its obligations, JouleClaw budgets dispatch against its ceiling. The durable artifact is the statement of intent — materialized it's code, verified it's a discharged obligation, executed it's a dispatch. The joule is the coordinate that puts a refactor, a settlement, and a clinical handoff on one ledger under one audit.
Must hold for the transition to be admissible. Checked against the contract version in force at the transition's start anchor — never against one that didn't exist yet.
Must hold once the transition completes. Binary: it holds or it doesn't, and the receipt says which tier closed it.
Must hold throughout and survive the boundary unchanged. The clause that crosses interfaces — a handoff, a settlement, a refactor — intact.
The declared mutable footprint: everything the transition may touch. Everything outside it is implicitly invariant, so an unstated effect is a breach exactly as a violated postcondition is. There is no closed “unbounded” frame.
Maximum energy, as an EnPI against a signed baseline, with a bound derivation. The one measured clause: it yields a residual — a control signal, never a savings claim.
A contract, on the wire
{
"joulecontract": "0.6.0",
"subject": "fn settle_batch(orders) -> Settlement",
"rigor_target": "JR-3",
"pre": ["all orders signed", "sum(debits) == sum(credits)"],
"post": ["ledger balanced", "each order has a settlement id"],
"inv": ["no order in two settlements", "no negative balance at any step"],
"frame": ["ledger table", "settlement index"],
"ceiling": {
"enpi_joules": 3.0, "unit": "EOC-J",
"enb_ref": "sha2-256:ab19…",
"derivation": { "basis": "metered median of 200 comparable batches", "signer": "did:web:energy-office.example" }
}
}Doctrine
Inherit. Bind. Seal.
One receipt discharges evidence for the functional-safety canon, the energy-management canon, and the AI-governance canon at once — three audit programs collapsed into three projections of one receipt log. The canon is composed, not reinvented; receipts pin the edition snapshot in force at issuance, so canon revisions never reinterpret past evidence.
Every trust-bearing field — generator, frame, qualification, independence, the joule figure itself — binds to a key, a sealed attestation, or an independent timestamp, or serializes a demoted state. A field that is named but not bound does not exist in a conformant receipt. Independence is computed from key disjointness; it is never copied from a producer's flag.
Conformance is evaluated once, at discharge, against a content-addressed evidence bundle, and sealed. Re-verification is resolution-free: no DNS, no live registry, no reachable authority — which is also what makes conformant receipts producible air-gapped. Receipts do not rot, and nothing re-grades them later.
Breach is deviation without amendment. Contracts bend instead of break: amendments are metered, independently timestamped transitions that govern the future only. A transition is judged end-to-end by the contract in force at its start anchor; a withheld receipt is visible as withheld; a past out-of-frame effect stays a breach forever; an unamended deviation caps the Governance class until closed. Adaptive systems still get auditability — every time a goalpost moves, who moved it and why is a signed, replayable record.
The receipt
One receipt. Three audits.
The contract is the promise; the receipt is the record that the promise held. One signed object carries the discharged obligations (the functional-safety assurance case), the joule figure with its bound measurement category (the energy-management EnPI), and the signature plus amendment chain (the governance change-control trail). A compliance report is a projection over the receipt log — the audit becomes a query, not a quarterly fire drill.
One entry per declared obligation — or the receipt is malformed, not demoted. Each carries its tier, the tier's qualification binding, the discharging verifier's identity, computed independence, and engagement disclosure.
The energy figure binds to a meter attestation signed by a non-signer key, or demotes. The residual against the ceiling is a control signal that drives the per-baseline ratchet — never a savings claim.
Dual independent anchors make the transition an interval, not a point. The sealed evidence bundle makes re-verification resolution-free: checkable in any enclave, at any later date, with no network.
Two tier classes, honestly split. Deterministic tiers — type checkers, SMT backends, static analyzers — are qualifiable and must carry qualification bindings. Stochastic tiers are not qualifiable, and the standard does not pretend otherwise: a model verdict alone never satisfies a high-rigor discharge; it must be re-discharged by a deterministic tier or an independent verifier. Inference is a bounded last resort, applied to verification itself.
Demotion
Record as untrusted. Never present as clean.
Demotion is the standard's universal answer to unverifiable claims: never forbid and drive underground, never launder into apparent trust. Twenty-two normative demoted states; ten of the most load-bearing below. Promotion — any downstream re-serialization that presents a demoted state as its bound counterpart — is prohibited for every state, by any consumer.
| State | Meaning | Effect |
|---|---|---|
| undischarged | An obligation no tier closed — including any unboundable frame | Caps Rigor below JR-3 |
| generator_unattested | Generator identity not bound to a non-signer attestation | Caps Governance at declared |
| qualified:false | Qualification unresolvable, expired at discharge, self-signed, or unterminated | Discharge counts as unqualified |
| independent:key_only | Keys disjoint but no party-level entity binding | Fails independence at JR-3+ |
| engagement_undisclosed | Verifier selection / compensation not disclosed | Fails independence at JR-3+ |
| metered_unattested | “Metered” without a sealed, non-signer meter attestation | Treated as ModelBased |
| ceiling_unanchored | Ceiling without a derivation binding to its baseline | Residual carries no weight |
| breach_unamended | Deviation with no forward-looking amendment or fix | Caps Governance until closed |
| timestamp_unanchored | Receipt without an independent timestamp where required | Predates every amendment |
| self_attested | Generation-loop receipt discharged only by the generator itself | Non-promotable |
Conformance
A composed profile. No single number to game.
JCAP = ⟨ Rigor · Energy · Governance ⟩ — gated by the least-bound axis: no axis can be inflated by assertion, and no axis's shine can halo another's demotion. JR is this standard's own scale; sector safety levels are claimable only through a bound risk-assessment attestation. And the claim-discipline rule: a conformance claim is the full tuple plus its demoted-state disclosure — the bare word “conformant” is itself a non-conformant claim.
Obligations declared; discharge recorded honestly. Demoted states permitted throughout — the floor is truthful disclosure, not silence.
Generator-independent frame discharge; bound generator identity. The transition's footprint is checked by someone who didn't produce it.
Bounded discharged frame; party-disjoint independence with engagement disclosure; qualified deterministic tiers per obligation; loop governance; verification and timestamp quorum; independent anchors on all receipts.
All of JR-3, plus the frame observed or witness-attested — never static-only — and formal discharge of every obligation by quorum verification.
Named residuals
What this standard cannot mechanize — graded, not hidden.
A standard that silently implied completeness it cannot have would contain illogic. JouleContract names its limits instead:
Discharge proves stated obligations; nothing certifies the obligation set is complete against the behavior space. The entire assurance canon shares this residual; a contract may carry a domain annex making the boundary of the claim auditable.
Party disjointness is bound by entity credentials; corporate control graphs are not mechanizable by any credential scheme. Entity binding moves the cost of manufactured independence from a domain registration to incorporation fraud — no further.
Engagement disclosure makes verifier capture legible — a relying party can see that every verifier is paid by the producer. It does not make capture impossible, and this standard does not claim it does.
This standard prices honesty; it cannot price assurance. A fully-demoted receipt is conformant by design — truthful disclosure beats driven-underground lying. Assurance is priced by relying parties demanding profiles.
Provenance
Hardened by adversarial diff — spec and implementation. The diffs are part of the standard.
Each version was attacked by independent, mutually-blind review lenses; the findings were published; the repairs were folded as traced amendments under the standard's own amendment model, chained to the real digest of the version they amend. Each round forced the standard to apply its own newest rule to its own oldest text. The standard improves by being adversarially diffed, not defended.
No frame clause, no generator identity, unqualified verifier tooling. Six gaps — the regulated canon's forty-year-old lessons (no unintended function; qualify the tool you trust) caught what the AI-coding canon misses, and vice versa.
Every field round one added was a string the producer could self-sign. Twenty findings: an escape-hatch frame, two unterminated recursions, retroactive breach legalization, and two canon over-claims a domain expert would seize on.
The joule itself was the last unbound field. Bindings had no evaluation point in time; keys are not parties and parties need consequences. Thirty-three findings, nine fix families — including binding the standard's own namesake.
The same method, turned on the code: four guarantee bypasses (case-variant key forgery, the entity-omission Party hole, caller-supplied key sets, reseal-under-any-key) and a validator over-grading JR-4 from receipt-local evidence. Twenty-eight findings, all blockers repaired — local validation now honestly caps at JR-2; JR-3+ is a composed verdict over sealed evidence, the key log, and the interval.
Could a third party build a conformant validator from the published artifacts alone? Half: the receipt-local path yes, the composed path no — the bundle construction, the negatives' sealed contexts, the key-log event model, and the quorum scope lived only in unreadable code, and the obvious canonicalization RFC produced the wrong digest. Seventeen findings: six definitions made normative, the pack expanded from thirteen to twenty-two vectors with every composed input shipped as bytes. The pack had been running evidence:external; v0.8 seals it.
The self-hosting amendment chain — real digests, byte-exact archive, mechanically verified by the conformance crate
The four diff documents ship in the repository under provenance/, and every prior version under archive/ — verify the chain yourself with shasum -a 256 archive/*.md.
Reference implementation
joulecontract-rs
A Rust workspace, Apache-2.0 — and the target of rounds four and five: the adversarial method was turned on the implementation (four guarantee bypasses, repaired in the same change that published the findings), then on the published artifacts themselves — a clean-room audit that asked whether a third party could rebuild the validator without reading this code, and expanded the conformance pack until the answer was yes. The attack scenarios from all five rounds run as tests — the Sybil-key attack reaches only key-only independence, the withheld receipt gains nothing, a case-variant key spelling is one identity, resealing under a forger's key is rejected — and the amendment digest chain is verified mechanically against the byte-exact archive. Receipt-local validation honestly caps at JR-2; JR-3 and JR-4 are composed verdicts over the sealed evidence bundle, the office key log, and the interval.
The core object (pre/post/inv/frame/ceiling), algorithm-prefixed content addressing over canonical JSON, the JCAP composed profile, and the full demoted-state vocabulary.
Receipt validation: one discharge entry per declared obligation or the receipt is malformed; computed independence; qualification evaluated at discharge; the least-bound-axis gates; the claim-discipline rule.
The content-addressed evidence bundle: sealing at discharge, Ed25519 envelopes, resolution-free offline re-verification, and the evidence-lost vs unresolvable distinction.
Forward-only disciplines: sealed intervals, start-anchor governance, breach classification (withheld receipts gain nothing), and the office key log with revocation windows.
The recognized edge: the receipt as an in-toto Statement (v1) with the JouleContract predicate type, wrapped in DSSE — exact PAE, Ed25519 over the envelope, verifiable with standard tooling.
The worked example through the composed path, the adversarial scenarios from all four diff rounds as tests, a regenerable signed vector pack, and mechanical verification of the amendment digest chain against the byte-exact archive.