9e6b8d32b4
The contract cargo class: 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 (a joule EnPI ceiling against a signed baseline) — discharged into one signed receipt that evidences functional safety, energy management, and AI governance at once. Doctrine: inherit don't invent, bind don't name, seal don't float — every trust-bearing field binds or serializes a demoted state, conformance seals once at discharge against a content-addressed evidence bundle (resolution-free, air-gapped capable), and breach is deviation without a timely amendment, with amendments governing the future only. Ships the v0.6.0 spec with its full amendment history: archive/ holds every prior version byte-exact so the SPEC §16 digest chain verifies, and provenance/ holds the three adversarial diff rounds whose findings drove each traced amendment. Reference workspace joulecontract-rs/ (schema, receipt, seal, amend, conformance) runs the diff-round attack scenarios as tests and mechanically verifies the digest chain. Root README catalogs joulecontract in the standards family, the tree, and the contribution guide. Site: joulecontract.transaction.science. Co-Authored-By: Claude Fable 5 <[email protected]>
229 lines
18 KiB
Markdown
229 lines
18 KiB
Markdown
# JouleContract
|
||
|
||
**An Open Standard for Energy-Accounted Interface Contracts**
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Status** | Draft for Review |
|
||
| **Version** | 0.3.0 — amends 0.2.0 (see Amendment Log, §13) |
|
||
| **Canonical home** | `joulecontract.transaction.science` |
|
||
| **License** | Specification text: CC-BY-4.0 · Reference implementation: Apache-2.0 (Rust) |
|
||
| **Stewardship** | The protocol is ownerless. Stewardship is an office, not an owner (§11). Transaction Science, Inc. is the inaugural steward. |
|
||
| **Position** | The operand between JouleCode, JouleProof, and JouleClaw; denominated in the EOC joule unit; readiness scored by ARL. |
|
||
| **Prime directive** | Energy optimization, safety, and auditability — served by one receipt, not three programs. |
|
||
|
||
---
|
||
|
||
## 0. Self-Hosting Clause
|
||
|
||
This specification is governed by its own amendment model. Each published version is a content-addressed document; each new version is an attributed, reasoned, signed amendment chained to the digest of the version it amends (§13). No version of this standard depends on any person, organization, algorithm, or jurisdiction remaining in place: every named fixed point in this document is an **office or a parameter with a defined succession or migration rule**, not a dependency.
|
||
|
||
---
|
||
|
||
## 1. Design Principle: Inherit, Don't Invent
|
||
|
||
The three concerns this standard serves — energy optimization, safety, auditability — each have a mature, internationally recognized management-system standard. JouleContract does not replace them. It is the technical control object whose single signed receipt simultaneously discharges evidence for functional safety (IEC 61508), energy management (ISO 50001 with ISO/IEC 30134), and AI governance (ISO/IEC 42001) — three programs collapsed into three projections of one receipt log.
|
||
|
||
Where an inherited standard is superseded, the inheritance binds to the **current edition** of that standard or its formally designated successor; this specification names roles ("the functional-safety standard," "the energy-management system"), with current editions listed in the non-normative Register (§12), so the standard does not break when the canon revises.
|
||
|
||
---
|
||
|
||
## 2. Normative Inheritance
|
||
|
||
Conformant implementations MUST be expressible in terms of the following, by role:
|
||
|
||
### 2.1 Safety — the functional-safety standard (currently IEC 61508; sector derivations where applicable)
|
||
Goal-based assurance: risk-reduction targets demonstrated through structured evidence across a defined lifecycle, with formal methods (model checking, theorem proving) admitted as assurance techniques, graded by Safety Integrity Level (SIL 1–4). JouleContract inherits the assurance-case-as-evidence model (the receipt log *is* the assurance case), the SIL grade, and RFC 2119 normative discipline.
|
||
|
||
### 2.2 Energy — the energy-management system (currently ISO 50001) + the measurement-KPI series (currently ISO/IEC 30134)
|
||
The joule ceiling is an **Energy Performance Indicator (EnPI)** against a declared **Energy Baseline (EnB)**; the ratchet (§5.3) is the continual-improvement loop; the provenance tag (§4.2) is the measurement category, with `Unaccounted` bound to the series' unaccounted-energy rules.
|
||
|
||
### 2.3 Governance — the AI management system (currently ISO/IEC 42001 and family: 23894, 42005, 42006, 42007, 38507, 5338)
|
||
The AIMS is the wrapper JouleContract operates inside; the amendment model (§5.2) is its change control; the contract is a control object within an AIMS, not a competing system.
|
||
|
||
### 2.4 Assurance, evidence, and trust
|
||
ISAE 3000 / SOC 2 (independent attestation reads the receipts) · eIDAS qualified signatures/seals/timestamps (EU legal effect) and FIPS 140-3 validated cryptography (US federal boundaries) · in-toto / SLSA / DSSE / Sigstore (supply-chain envelope at the recognized edge, §7) · ISO 19011 (the audit is a query over the receipt log).
|
||
|
||
---
|
||
|
||
## 3. The Core Object
|
||
|
||
A JouleContract is a content-addressed object bound to a unit of work, declaring four obligations:
|
||
|
||
1. **Precondition (`pre`)** — MUST hold for the transition to be admissible.
|
||
2. **Postcondition (`post`)** — MUST hold once the transition completes.
|
||
3. **Invariant (`inv`)** — MUST hold throughout and survive the boundary unchanged.
|
||
4. **Joule ceiling (`ceiling`)** — maximum energy, in the EOC joule unit, expressed as an EnPI against a declared EnB.
|
||
|
||
### 3.1 Identity and cryptographic agility
|
||
|
||
A contract MUST be content-addressed by the digest of its canonical serialization. The digest MUST be **algorithm-prefixed** (multihash-style: `sha2-256:…`, `sha3-256:…`), and conformant implementations MUST support digest-algorithm migration: when an algorithm is deprecated by the steward (§11) on published cryptanalytic grounds, existing objects are re-anchored by a signed cross-digest amendment mapping old identity to new. No object's validity depends on the permanence of any single hash function or signature scheme. (Resolves the v0.2 hard dependency on SHA-256.)
|
||
|
||
### 3.2 Correctness stays the verifier's
|
||
|
||
A contract states a specification; it does not certify itself. A proof is not a specification: discharge establishes that an implementation satisfies the stated obligations, not that those were the right obligations. Conformant systems MUST keep correctness with an independent verifier of record (§6).
|
||
|
||
### 3.3 Composition
|
||
|
||
Contracts compose. A contract over a composed transition (a batch, a pipeline, a workflow) is the conjunction of its components' obligations with a ceiling no greater than the sum of component ceilings. Composition is associative; receipts for a composed transition MUST reference the component receipts or carry the composed discharge directly.
|
||
|
||
---
|
||
|
||
## 4. Energy as Coordinate
|
||
|
||
Energy is the coordinate system, not a feature. The joule is the only unit present in every transition in every domain; that shared unit is what places a refactor, a settlement, and a clinical handoff on one ledger under one audit.
|
||
|
||
### 4.1 The ceiling is the one measured clause
|
||
Correctness clauses are binary; the ceiling yields a **measured residual** (allowed − spent) — the continuous signal that improvement loops and energy disclosures (CSRD/ESRS E1) sum over.
|
||
|
||
### 4.2 Energy provenance = measurement category
|
||
Every joule figure MUST carry one of: **`Metered`** (hardware-measured) > **`ModelBased`** (anchored to a metered baseline for a comparable workload) > **`Unaccounted`** (estimated by published energy-traceability methods where the substrate exposes nothing). The tag MUST travel with the number; downstream consumers MUST NOT promote a category. The failure prevented is estimation laundering itself into apparent measurement.
|
||
|
||
### 4.3 Cross-domain ledger rule (resolved by principle)
|
||
|
||
The ledger is **additive across domains and comparative only within an EnB scope.**
|
||
|
||
The joule is an SI unit; sums of joules are physically meaningful regardless of domain, so a global ledger MAY total compute-joules and operational work-joules for aggregate disclosure. But an EnPI is meaningful only against its own baseline: a contract's residual is comparable to other residuals **under the same EnB**, and never constitutes an equivalence claim across EnBs. A handoff's joules and a refactor's joules add on the ledger; they are never exchanged, ranked, or netted against each other. Receipts MUST carry the EnB reference, and conformant ledgers MUST refuse cross-EnB comparison operations while permitting cross-EnB summation. (Resolves v0.2 Open Question 2 — no false equivalence is possible by construction, because the comparison operation that would assert it is not defined.)
|
||
|
||
---
|
||
|
||
## 5. The Receipt, the Amendment, and the Ratchet
|
||
|
||
The contract is the promise; the receipt is the record that the promise held — the unit of evidence for all three inherited management systems at once. Any compliance report is a projection over the receipt log.
|
||
|
||
### 5.1 Required receipt fields
|
||
`contract` · `transition` · `discharge` (per obligation: tier that closed it, or `undischarged` + reason) · `execution` · `joules_spent` · `joules_allowed` · `residual` · `provenance` · `enb_ref` · `grid_mix` (OPTIONAL) · `verifier` · `profile` (§10) · `signature`.
|
||
|
||
### 5.2 Amendment model
|
||
Every amendment to a contract — including to its ceiling — is an attributed, reasoned, signed transition chained to the prior digest. The contract is its own amendment log. **Breach is deviation without a matching amendment**; a measured overrun with a signed, reasoned amendment is governed change. (This is functional-safety modification control and AIMS change control expressed as a ledger.)
|
||
|
||
### 5.3 Enforcement and ratchet
|
||
Enforcement is at receipt-time (observed), never compile-time (rigid): deviations are recorded, the system keeps running, resolution is amend-or-fix. Over successive transitions the ceiling MAY ratchet toward the measured floor and reject regressions, without touching correctness obligations.
|
||
|
||
### 5.4 Granularity (resolved by principle)
|
||
|
||
The standard fixes no transition granularity. Granularity is discovered economically by the cheapest-sufficient discharge cascade: where per-transition discharge is cheaper than the obligation's risk warrants, transitions stay fine-grained; where it is not, obligations batch by composition (§3.3) until discharge clears at an acceptable tier, and the receipt records the batch boundary. The cascade's disclosed escalation makes the chosen granularity itself auditable. (Resolves v0.2 Open Question 1 — tractability is priced, not legislated.)
|
||
|
||
---
|
||
|
||
## 6. Independent Verification — no single verifier as point of failure
|
||
|
||
Conformant systems MUST designate a **verifier of record** distinct from the generator of the work; where one agent drafts both obligation and implementation, an independent checker MUST discharge the obligation. At SIL-3 and above, the verifier of record MUST be replaceable without invalidating prior receipts (verification authority attaches to the *office and its published keys*, not the incumbent), and implementations SHOULD support **quorum verification** (k-of-n independent verifiers) so that no single verifier's compromise, capture, or disappearance is a point of failure. This one requirement discharges the independent functional-safety assessment (IEC 61508), effective challenge (SR 11-7), and independent attestation (ISAE 3000), and corresponds to receiver-confirmation ("synthesis by receiver") in clinical handoff protocols such as I-PASS.
|
||
|
||
---
|
||
|
||
## 7. Wire Format and Recognized-Edge Emission
|
||
|
||
Novel core, recognized edge. Contract and receipt serialize as canonical JSON (JSON Web Proof permitted for selective disclosure). A receipt MUST be expressible as an in-toto Statement with a `JouleContract` predicate type wrapped in DSSE, and MAY carry a SLSA provenance predicate. Signatures MUST verify with standard tooling; eIDAS qualified signatures/seals for EU legal effect; FIPS 140-3 validated cryptography for US federal boundaries; signature schemes are algorithm-agile under §3.1. Governance mappings SHOULD emit as OSCAL; energy figures SHOULD be reportable as ISO/IEC 30134 KPIs and ISO 50001 EnPIs.
|
||
|
||
---
|
||
|
||
## 8. Regulatory and Standards Mapping
|
||
|
||
| JouleContract element | Recognized standard / control |
|
||
|---|---|
|
||
| Discharged obligation + SIL grade | IEC 61508 assurance case & SIL; ISO 26262 / IEC 62304 (sector) |
|
||
| Independent verifier / quorum | IEC 61508 FS assessment; SR 11-7; ISAE 3000 |
|
||
| Signed receipt per transition | 21 CFR Part 11; NIST 800-53 **AU**; eIDAS |
|
||
| Amendment = signed transition | ISO/IEC 42001 change control; NIST 800-53 **CM**; SOX; DORA |
|
||
| Continuous receipt log | NIST 800-53 **CA** ConMon; EU AI Act record-keeping; ISO 19011 |
|
||
| Joule ceiling as EnPI vs EnB | ISO 50001 |
|
||
| Energy provenance category | ISO/IEC 30134 measurement categories & unaccounted-energy rules |
|
||
| Residual + grid-mix | CSRD / ESRS E1; ISO/IEC 30134-8 (CUE) |
|
||
| Governance wrapper | ISO/IEC 42001 AIMS (certifiable per 42006) |
|
||
|
||
---
|
||
|
||
## 9. Lineage
|
||
|
||
Hoare logic and Dijkstra's weakest precondition (the obligation generator) · Meyer's Design by Contract (pre/post/invariant in the signature; the joule ceiling is one more clause) · Knuth's literate programming (intent is the durable source; code is extracted) · the governance canon itself (IEC 61508; ISO 50001; ISO/IEC 42001), composed rather than reinvented. The name "pseudocode" is declined as homage: *pseudo* means false, and this is the most rigorous artifact in the stack, not the least.
|
||
|
||
---
|
||
|
||
## 10. Conformance: a Composed Profile
|
||
|
||
```
|
||
JCAP = ⟨ Safety class, Energy class, Governance class ⟩
|
||
```
|
||
|
||
Safety class: SIL 1–4 (or sector equivalent; SIL 4 implies formal discharge by independent/quorum verification). Energy class: `Metered` > `ModelBased` > `Unaccounted`. Governance class: AIMS maturity from declared to certified. A `⟨SIL-3, Metered, certified⟩` transition is categorically stronger than `⟨SIL-3, Unaccounted, declared⟩`, and the profile says so. There is no single number to game.
|
||
|
||
---
|
||
|
||
## 11. Stewardship Succession — no organization as point of failure
|
||
|
||
Stewardship is an **office**. The protocol is ownerless; the steward maintains the Register (§12), publishes algorithm deprecations (§3.1), and convenes amendment review. The office is bound by:
|
||
|
||
- **Fork-freedom.** The specification license (CC-BY-4.0) and reference implementation license (Apache-2.0) guarantee that any party may continue the standard if the steward fails, defects, or captures. The ultimate succession mechanism is the license itself.
|
||
- **Succession rule.** The steward MAY transfer the office by signed amendment to this specification. If the steward is dissolved or unresponsive for a published timeout, any party maintaining a conformant reference implementation MAY assume interim stewardship by signed public declaration; competing claims resolve by implementer adoption, which the amendment log makes auditable.
|
||
- **No retroactive authority.** A steward cannot invalidate prior receipts or prior versions; all authority is forward-looking and exercised only through traced amendments.
|
||
|
||
---
|
||
|
||
## 12. Register (non-normative)
|
||
|
||
Current editions of inherited standards as of this version: IEC 61508:2010 (Ed. 2) · ISO 50001:2018 · ISO/IEC 30134-2:2026 · ISO/IEC 42001 (current edition; EN ISO/IEC 42001:2026 in the EU) · ISO/IEC 42005:2025, 42006:2025 · eIDAS (Reg. 910/2014 as amended) · FIPS 140-3 · SLSA v1.2 · RFC 2119/8174. The Register is updated by steward amendment and never alters normative text by itself.
|
||
|
||
---
|
||
|
||
## 13. Amendment Log
|
||
|
||
Each entry: version, amends-digest, change, reason. The log is normative history; the standard practices its own §5.2.
|
||
|
||
**v0.3.0** — amends `sha2-256:<digest of v0.2.0>`
|
||
1. **Added §0 Self-Hosting Clause.** *Reason:* the standard must be governed by its own amendment model; a spec that imposes traced change control but evolves untraced is illogical.
|
||
2. **§3.1 Cryptographic agility** (algorithm-prefixed digests; migration rule). *Reason:* hardcoded SHA-256 was a single point of failure against cryptanalytic time.
|
||
3. **§4.3 Cross-domain ledger rule.** *Reason:* v0.2 left unit reconciliation as an open question dependent on a person. Resolved by principle: joules sum across domains (SI), compare only within an EnB scope; false equivalence is impossible by construction because the cross-EnB comparison operation is undefined.
|
||
4. **§5.4 Granularity resolved economically.** *Reason:* v0.2 Open Question 1. The cheapest-sufficient cascade prices granularity; legislating a fixed grain would be arbitrary and would break across domains.
|
||
5. **§6 Verifier office + quorum option.** *Reason:* a single named verifier was a point of failure (compromise, capture, disappearance); authority attaches to the office and keys, with k-of-n available at high assurance.
|
||
6. **§11 Stewardship as office with succession and fork-freedom.** *Reason:* a named company was a single point of failure; the license is the ultimate succession mechanism; no retroactive authority.
|
||
7. **§1 + §12 Inheritance by role with a Register.** *Reason:* binding to specific editions would break the standard whenever the canon revises; roles endure, editions rotate.
|
||
8. **Removed "first mandate vector" from open questions.** *Reason:* adoption strategy is a property of the world, not of the standard; a document built to stand the test of time carries no market-timing content.
|
||
9. **Added §3.3 Composition.** *Reason:* required by §5.4; batching without a composition rule would be unsound.
|
||
|
||
**v0.2.0** — amends `sha2-256:<digest of v0.1.0>`. Re-founded all structure on the recognized canon (IEC 61508, ISO 50001/30134, ISO/IEC 42001); replaced the invented conformance ladder with the composed profile.
|
||
|
||
**v0.1.0** — genesis. Core object (pre/post/inv/ceiling), receipt, amendment-as-transition, breach redefinition, energy-as-coordinate, verifier-of-record, recognized-edge emission.
|
||
|
||
---
|
||
|
||
## Appendix A — Example (informative)
|
||
|
||
```json
|
||
{
|
||
"joulecontract": "0.3.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 in two settlements", "no negative balance at any step"],
|
||
"ceiling": { "enpi_joules": 3.0, "unit": "EOC-J", "enb_ref": "sha2-256:ab19…" },
|
||
"amends": "sha2-256:9b2c…"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"ReceiptPayload": {
|
||
"contract": "sha2-256:1f4a…",
|
||
"transition":"sha2-256: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": "Metered",
|
||
"enb_ref": "sha2-256:ab19…",
|
||
"grid_mix": { "renewable": 0.61, "region": "eu-w-1" },
|
||
"verifier": ["did:web:audit-a.example", "did:web:audit-b.example"],
|
||
"profile": { "safety": "SIL-3", "energy": "Metered", "governance": "certified" },
|
||
"signature": "eIDAS-QES…"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
*End of v0.3.0 — a traced amendment of v0.2.0 under the standard's own §5.2.*
|