# JouleContract

A carrier for obligation. Five clauses, one signed receipt, owned by no one.

JouleContract is the **contract cargo class** of the Transaction Science substrate. Where Smart Byte carries value, EOC carries compute, Joule Code carries coding work, and Map carries place, JouleContract carries **the promise itself**: a content-addressed statement of what a unit of work must hold (`pre`, `post`, `inv`), what it may touch (`frame`), and what it may spend (`ceiling`, a joule EnPI against a signed baseline). It is the operand the rest of the family acts on — Joule Code carries its changes, the proof standard discharges its obligations, JouleClaw budgets dispatch against its ceiling — and its single signed receipt simultaneously evidences functional safety, energy management, and AI governance: three audit programs collapsed into three projections of one receipt log.

## The doctrine

**Inherit, don't invent — bind, don't name — seal, don't float.** Three normative consequences:

1. **The binding rule.** 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 one of twenty-two **demoted states**. A field that is named but not bound does not exist in a conformant receipt. `Metered` without a meter attestation is `metered_unattested`; independence is computed from key disjointness, never copied from a producer's flag.
2. **The sealing rule.** 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.
3. **Breach is deviation without amendment.** Contracts bend instead of break: amendments are metered, independently timestamped transitions that govern the future only. 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.

## Rigor, honestly

Conformance is a composed profile — ⟨Rigor JR-1..4 · Energy class · Governance class⟩ — gated by the least-bound axis, with a claim-discipline rule: the bare word "conformant" is itself a non-conformant claim. The limits no document can mechanize are **named residuals**, not hidden: obligation-set adequacy, common control, issuer-pays gravity, and the demand side — the standard prices honesty; relying parties price assurance.

## Provenance

This standard was hardened by adversarial diff, and the diffs are part of it: each version was attacked by independent review lenses, the findings published, and the repairs folded as traced amendments with real digests. `SPEC.md` §16 carries the full chain; `archive/` holds every prior version byte-exact so the chain verifies; `provenance/` holds the four diff rounds that produced it — three against the spec text, the fourth against the reference implementation itself.

## Contents

- `SPEC.md` — normative specification v0.6.0 (RFC 2119), self-hosting amendment log with verified digest chain.
- `archive/` — prior spec versions (v0.1.0–v0.5.0), byte-exact anchors of the amendment chain.
- `provenance/` — the adversarial diff rounds that drove each amendment.
- `joulecontract-rs/` — Rust reference workspace: schema, receipt validation, evidence sealing, amendment/key-log machinery, conformance harness.

## Reference implementation and consumers

`joulecontract-rs` implements the core object, the demoted-state vocabulary, computed independence, the least-bound-axis profile gates, resolution-free sealed verification, and forward-only temporal ordering. The first family consumer is live: [`joule-code-joulecontract`](../joule-code/joule-code-rs/crates/joule-code-joulecontract/) runs a coding operation under a contract — the edit set is the frame, the tier cost is the ceiling, JCR provenance maps downward-only onto the energy classes — and discharges it into a receipt that grades honestly under the two-stage rule. The JouleClaw runtime and the proof standard's cascade are next.

## Status

**v0.8.0 draft.** The amendment chain is real (archive digests verify against §16, mechanically, on every `cargo test` — seven anchors, v0.1 through v0.7). The reference workspace covers the schema, the receipt-local and **composed** validators (two-stage evaluation is now normative: local witnesses at most JR-2; JR-3/JR-4 and `certified` are composed verdicts over the sealed evidence bundle, the office key log, and the transition interval), composition with per-component ceiling accountability (intra-batch netting is structurally dead), the per-EnB ratchet, recourse and sector-equivalence bindings, the mechanical lost/never evidence distinction, cross-digest re-anchoring, evidence sealing with expected-signer verification, the in-toto/DSSE recognized edge, and a regenerable conformance vector pack whose expected verdicts come from the validators themselves. Five adversarial rounds are on the record (`provenance/`): three against the spec text, the fourth against the implementation (28 findings, four guarantee bypasses, all repaired — folded back as v0.7), and the fifth a **clean-room implementability audit** of the published artifacts alone, which found the composed validation path unbuildable without reading the reference code — folded back as v0.8, which makes the bundle construction, canonical JSON, quorum scope, obligation matching, and key-log event model normative text, and expands the pack from 13 to 22 vectors with every composed input shipped (member bytes included). **Every §15 demoted state is producible by the reference implementation, and a third party can now build the composed validator from the published artifacts alone.**

## Licence

- Reference code: Apache-2.0
- Specification text: CC-BY-4.0