open-standards/joulecontract/archive/joulecontract-spec-v0.1.md

JouleContract

An Open Standard for Energy-Accounted Interface Contracts

Status	Draft for Review
Version	0.1.0
Canonical home	joulecontract.transaction.science
License	Specification text: CC-BY-4.0 · Reference implementation: Apache-2.0 (Rust)
Stewardship	The protocol is ownerless. Transaction Science, Inc. is the steward.
Position	The operand between JouleCode, JouleProof, and JouleClaw; denominated in the EOC joule unit; readiness scored by ARL.

---

Abstract

A JouleContract is a content-addressed, signed statement of what must be true across a transition and what that transition is permitted to cost. It carries four obligations over a unit of work — a precondition, a postcondition, an invariant, and a joule ceiling — and it is the durable artifact from which code is materialized, against which proofs are discharged, and within which runtime dispatch is budgeted.

Complex systems fail at their interfaces. A JouleContract is a contract over an interface crossing. Its scope is not software; its scope is any transition where work transforms state and an invariant must survive the boundary. Energy is the coordinate that makes those transitions — a refactor, a wire transfer, a clinical shift handoff — a single class of object on one ledger, in one billing unit, under one audit.

---

1. Motivation

The cost of generating code has collapsed. When generation is near-free, the code is the disposable artifact: regenerable, cacheable, a materialization. The durable artifact is the statement of intent — what the code is for, what it must preserve, what it may cost. Current tooling optimizes generation of the disposable thing and neglects the durable one.

Two ecosystems each hold half of what regulated environments require, and neither holds both:

• Spec-driven development (Spec Kit, Kiro, OpenSpec, and others) makes intent the source of truth and treats code as last-mile output. It captures intent forward. But the spec is unenforced prose that drifts from the implementation, carries no proof obligation, and is blind to energy.
• Supply-chain provenance (SLSA, in-toto, Sigstore) binds an artifact to its origin: this digest, from this workflow, this commit, this identity. It proves who and how. It says nothing about whether the change preserves an invariant, and nothing about what it cost.

Spec-driven development gives "what was intended." Provenance gives "who produced it." No standard binds, per transition, a single object carrying origin, intent, correctness, and energy. JouleContract occupies that seam.

The neglected truth this standard is built on: regulated environments do not principally require correctness. They require documented change control — who changed what, when, why, was it authorized, was it reviewed, can it be replayed. Every such regime is an amendment-log regime. The object below is their native shape, not an adaptation to them.

---

2. Position in the Stack

JouleContract is a noun. The surrounding standards are verbs that act on it.

Standard	Relationship to the contract
JouleCode	Carries mutations of the contract and of the source tree it governs, as content-addressed signed transitions.
JouleProof	Discharges the obligations generated from the contract's pre/post/invariant, via a cheapest-sufficient solver cascade with disclosed escalation.
JouleClaw	Budgets and executes dispatch against the contract's joule ceiling, through its L0–L4 cascade, and measures actual joules spent.
EOC	Defines the joule as the billing unit and exposes grid-mix per call; the contract's ceiling is denominated in this unit.
ARL	Scores the readiness of a system to operate under a given contract class.

Materialized, a contract is code. Verified, it is a discharged obligation. Executed, it is a metered dispatch. Before any of those, it is a statement of what must hold and what it may cost.

---

3. The Core Object

A JouleContract is a content-addressed object bound to a unit of work. It declares four obligations.

3.1 Obligations

1. Precondition (pre) — what MUST hold for the transition to be admissible.
2. Postcondition (post) — what MUST hold once the transition completes.
3. Invariant (inv) — what MUST hold throughout, and MUST survive the boundary unchanged.
4. Joule ceiling (ceiling) — the maximum energy, in the EOC joule unit, the transition is permitted to spend.

The first three are the inheritance of Hoare logic and Design by Contract (§12). The fourth is this standard's distinguishing clause — but see §4: energy is not merely a fourth clause.

3.2 Identity

A contract MUST be content-addressed by the SHA-256 digest of its canonical serialization. The digest is the contract's identity. Two contracts with identical obligations are the same contract. A contract referenced by a transition, a proof, or a receipt MUST be referenced by digest.

3.3 Correctness stays the verifier's

A contract states a specification. It does not certify itself. A proof is not a specification: discharging the obligation establishes that an implementation satisfies the stated pre/post/invariant — not that the stated obligations are the ones the world actually needed. Conformant systems MUST keep correctness with an independent verifier of record (§7). A contract that certifies its own correctness is non-conformant.

---

4. Energy as Coordinate

Energy is not a feature of this standard. It is the coordinate system.

pre, post, and inv describe what must survive a transition. The joule is the only unit present in every transition across every domain: a refactor, a settlement, a drug infusion, and a shift handoff are all energy becoming work in the world. That shared unit is what lets transitions from unrelated domains share one ledger, one receipt format, and one audit. Energy is what makes the contract domain-agnostic rather than a coding standard with separate editions per vertical.

Two consequences follow:

• The ceiling is the one measured clause. Correctness clauses are binary — they hold or they do not. The joule ceiling produces a measured residual: spent against allowed, with energy to spare or over. That residual is a continuous signal the correctness clauses cannot give, and it is what compliance projections (e.g. CSRD/ESRS E1) sum over.
• The ceiling ratchets. Because the residual is measured, a contract MAY tighten its ceiling toward the measured floor over successive transitions, and reject regressions, without touching its correctness obligations.

Energy provenance is first-class. Every joule figure MUST carry a provenance tag (§5.2), because a figure backed by a hardware shunt is a different trust object than one backed by an estimator, and the audit leans on which is doing the work.

---

5. The Receipt

The contract is the promise. The receipt is the record that the promise held.

Every transition governed by a contract MUST emit a signed ReceiptPayload. The receipt is the unit of evidence. A compliance report is a projection over the receipt log — not a separately compiled document.

5.1 Required fields

• contract — digest of the governing contract.
• transition — digest of the JouleCode transition this receipt attests.
• discharge — for each correctness obligation: the JouleProof tier that closed it, or undischarged with reason.
• execution — the JouleClaw tier(s) that executed the work.
• joules_spent — measured energy in the EOC unit.
• joules_allowed — the ceiling in force at execution time (the digest of the governing contract version).
• residual — joules_allowed − joules_spent.
• provenance — the energy-figure provenance tag (§5.2).
• grid_mix — OPTIONAL; the EOC grid-mix attribution for the spent joules.
• verifier — identity of the independent verifier of record (§7).
• signature — see §8.

5.2 Energy provenance tags

The provenance field MUST be one of:

• HwShunt — measured at hardware.
• ModelBased — derived from a model anchored to a hardware-shunt baseline for a comparable workload.
• Estimator — estimated from published energy-traceability methods where the substrate exposes no measurement (e.g. opaque cloud VMs, containers).

An Estimator figure is a defensible trust object only while the tag travels with the number. Downstream consumers MUST NOT treat Estimator joules as HwShunt joules. The failure mode this prevents is not estimation; it is estimation laundering itself into apparent measurement.

---

6. The Amendment Model

A rigid contract is a state, and states break under changing conditions. A silently soft contract is no contract, because deviations vanish. JouleContract is neither: it is amendable, and every amendment is itself a signed JouleCode transition over the contract.

• A contract's obligations — including its ceiling — MAY change. Each change is a content-addressed, attributed, reasoned amendment, signed, and chained to the prior contract digest.
• The contract is therefore not a fixed value. It is its own amendment log: a sequence, and sequences bend where states shatter.
• Breach is redefined. Breach is not "the ceiling was exceeded" or "a postcondition failed." Breach is deviation without a matching amendment — an invariant that crossed the boundary undischarged, or joules spent past a ceiling with no amendment authorizing the new ceiling. A measured overrun accompanied by a signed, reasoned amendment is governed change, not breach.

6.1 Enforcement is at receipt-time

Enforcement MUST occur at receipt-time (observed), not at compile-time (rigid). The runtime measures actual joules and discharge outcomes; a receipt whose joules_spent exceeds the in-force ceiling, or whose obligations are undischarged, with no matching amendment in the log, is the flagged finding. The system keeps running; the deviation is recorded; resolution is amend-or-fix.

The auditability claim this produces is stronger than absolutes: not "this system never exceeds its budgets," but "every change to a budget or an obligation in this system is a signed amendment you can replay — who moved it, when, and why." Change control, not perfection, is what regulated audits assess.

---

7. Verification and Independent Challenge

Conformant systems MUST designate a verifier of record distinct from the generator of the work. Where the same agent (human or model) drafts both the obligation and the implementation, an independent checker MUST discharge the obligation, or the "correctness stays the verifier's" requirement (§3.3) collapses into self-certification.

This requirement maps directly to existing regulated practice — for example, the "effective challenge" expected of model risk management under SR 11-7, and the receiver-confirmation step ("synthesis by receiver") in clinical handoff protocols such as I-PASS. In both, an independent party restates and accepts the obligation before it is considered discharged. JouleContract makes that step a recorded discharge rather than an unenforced hope.

---

8. Wire Format and Recognized-Edge Emission

The core object is novel; the boundary MUST speak the vocabularies that auditors and pipelines already accept. Novel core, recognized edge.

• A contract and a receipt are serialized as canonical JSON; the ReceiptPayload MAY be encoded as a JSON Web Proof (JWP) for selective disclosure.
• For supply-chain interoperability, a receipt MUST be expressible as an in-toto Statement with a JouleContract predicate type, wrapped in a DSSE envelope, and MAY be expressed as a SLSA provenance predicate.
• Signatures MUST be verifiable with standard tooling (e.g. Sigstore/cosign). For deployment into US federal and equivalent regulated boundaries, signing keys SHOULD use FIPS 140-3 validated cryptography.
• For governance interoperability, contract-to-control mappings (§9) SHOULD be emitted as OSCAL.

A conformant system that cannot present its receipts in at least one recognized edge format (in-toto/DSSE or OSCAL) does not meet JC-4 (§11).

---

9. Regulatory Mapping (the Floor)

Each element of the standard corresponds to an obligation that change-control and evidence regimes already impose. This table is the "floor": what a regulated buyer will recognize on sight.

JouleContract element	Recognized control
Signed receipt per transition	NIST 800-53 AU (Audit & Accountability); 21 CFR Part 11 audit-trail (electronic records & signatures)
Amendment = signed transition	NIST 800-53 CM (Configuration / change management); SOX change control; DORA ICT change management
Continuous receipt log	NIST 800-53 CA continuous monitoring (ConMon); EU AI Act record-keeping/traceability obligations
Independent verifier of record	SR 11-7 effective challenge; CMMC / NIST 800-171 separation-of-duties
Content-addressed origin + identity	SLSA Source Track; in-toto attestation; signed change intent
Joule ceiling + residual + grid-mix	CSRD / ESRS E1 energy & emissions disclosure (EU); cost attribution (everywhere)

The compliance deliverable is therefore not a separate artifact. The SOC 2, ConMon, Part 11, or CSRD report is a query over the receipt log.

---

10. Domain-Agnosticism

JouleContract governs interface crossings, not files. The same object covers a software transition and a non-software one.

Worked example — clinical shift handoff. A handoff is a transition: a patient's care state moves from an outgoing caregiver to an incoming one. Today it is a state handoff with no contract — verbal, ad hoc, degrading under fatigue and time — and critical invariants (code status, allergy, NPO order, time-critical medication, fall risk) are held in one person's head and dropped at the boundary. The domain already wrote the pseudocode for this (SBAR, I-PASS): readable, intent-bearing, unenforced, first skipped under pressure.

As a JouleContract:

• pre — the enumerated invariants hold at the start of the handoff.
• post — the incoming caregiver has acknowledged and can restate each invariant (the I-PASS "synthesis by receiver" step, made a discharge rather than a hope).
• inv — no critical item crosses the boundary unverified.
• ceiling — the work budget of performing the handoff; its residual is measured.
• receipt — who handed what, when, acknowledged or flagged-unresolved, signed by both parties.

Breach stops meaning "a patient was harmed." It means "an invariant crossed the boundary without being discharged" — caught at the interface, in the cheap joules of confirmation, not discovered later in the chart review. This is energy-optimized compute generalized past silicon: spend the cheap joules at the boundary so the catastrophic joules of failure are never paid.

---

11. Conformance Levels

Graduated, in the manner of TRL, SLSA, and ARL, so adoption can ramp.

Level	Name	Requirement
JC-0	None	No contract. State is handed across the interface with no enforceable obligations.
JC-1	Declared	pre/post/inv/ceiling are stated, content-addressed, and human-readable. Work MAY be generated against the contract. No enforcement.
JC-2	Receipted	Every transition emits a signed receipt binding contract digest to outcome and measured joules with a provenance tag. Amendments are signed transitions. (The audit floor: change control.)
JC-3	Discharged	Correctness obligations are discharged by JouleProof's cheapest-sufficient cascade with disclosed escalation; an independent verifier of record is named; the ceiling is checked against the measured residual.
JC-4	Attested-energy	The joule figure is HwShunt wherever the substrate permits; recognized-edge emission (in-toto/DSSE or OSCAL) is mandatory; receipts participate in a cross-domain ledger.

The frontier sits at JC-4. The floor regulated buyers already demand sits at JC-2. The standard is built so that energy is load-bearing from JC-2 upward, not retrofitted when grid limits, CSRD, and AI power draw force the awareness.

---

12. Prior Art and Lineage

The standard's correctness obligations are not new mathematics; they are a credited inheritance.

• Hoare logic; Dijkstra's weakest precondition — the {P} C {Q} triple is the obligation generator. JouleProof discharges what the contract states in these terms.
• Meyer, Design by Contract (Eiffel) — pre/post/invariant in the signature. JouleContract's move is to recognize that a joule budget is simply another contract clause: pre, post, invariant, and cost ceiling.
• Knuth, literate programming (1984) — the program is written for humans, and machine output is extracted from it. This is the same inversion four decades early: intent is the durable source, code its materialization.

On the name: this object is sometimes reached for as "pseudocode," in homage. The homage is declined. Pseudo means false, and this is the source of truth in the stack — the most rigorous artifact, not the least. Pseudocode was the field's disposable, unenforced approximation; naming the durable, checkable, energy-accounted object after it would enshrine the two properties this standard inverts.

---

13. Security Considerations

• Signature integrity. A receipt's trust derives entirely from its signature and the identity binding. The Key ID hint in any envelope MUST NOT be trusted for verification; verifiers MUST resolve to a trusted key.
• Estimator abuse. Because Estimator joules are unverifiable at the substrate, a hostile actor could under-report energy. Mitigation: ModelBased and Estimator figures SHOULD be periodically reconciled against HwShunt baselines on measurable substrates, and large unexplained residual swings flagged.
• Amendment flooding. The amendment model can be abused to legitimize breaches retroactively. Mitigation: amendments are themselves attributed, reasoned, signed transitions subject to the same independent-challenge requirement; an audit can detect amendments that consistently trail their own overruns.
• Self-certification drift. Where a model both generates and verifies, the independent-verifier requirement (§7) is the only barrier to silent self-certification and MUST NOT be waived at JC-3 or above.

---

14. Open Questions

• Granularity: at what transition size does proof-per-transition stay tractable under the cheapest-sufficient cascade, and where must obligations be batched?
• Cross-domain unit reconciliation: how are biological/operational work joules (a handoff) and compute joules (a refactor) normalized on a single ledger without false equivalence?
• The first mandate vector: which authority first references JouleContract conformance in a procurement or conformity context, since adoption timeline is governed by that reference and not by the standard's quality.

---

Appendix A — Example (informative)

A contract and the receipt that attests one transition under it.

{
  "joulecontract": "0.1.0",
  "subject": "fn settle_batch(orders) -> Settlement",
  "pre":  ["all orders signed", "sum(debits) == sum(credits)"],
  "post": ["ledger balanced", "each order has a settlement id"],
  "inv":  ["no order visible in two settlements", "no negative balance at any step"],
  "ceiling": { "joules": 3.0, "unit": "EOC-J" },
  "amends": "sha256:9b2c…(prior contract digest, or null)"
}

{
  "ReceiptPayload": {
    "contract":  "sha256:1f4a…",
    "transition":"sha256:77de…",
    "discharge": [
      { "obligation": "ledger balanced", "tier": "JP-L1-typecheck", "result": "closed" },
      { "obligation": "no negative balance", "tier": "JP-L3-smt", "result": "closed" }
    ],
    "execution": ["JC-L0-cache", "JC-L3-model"],
    "joules_spent": 2.1,
    "joules_allowed": 3.0,
    "residual": 0.9,
    "provenance": "HwShunt",
    "grid_mix": { "renewable": 0.61, "region": "eu-w-1" },
    "verifier": "did:web:audit.example.org",
    "signature": "DSSE…"
  }
}

---

End of draft v0.1.0. This is a draft for review; sections 11 and 14 in particular invite revision.