open-standards/joule-os/README.md

Joule OS

An operating system that bills in joules. The UDA reference runtime, owned by no one.

Joule OS is the runtime the rest of the substrate lowers onto. Where Smart Byte carries value, EOC carries compute, Joule Code carries coding work, and Map carries place, Joule OS is the single-level store and dispatch fabric those cargo classes execute against — a realization of the Unified Design Architecture (UDA) on commodity hardware.

The thesis: hardware, runtime, language, and surface are one co-designed artifact. The reality: we don't own the silicon — so the runtime measures where it is and lowers accordingly. One intent IR is specialized at boot against a control vector — address-space ownership, capability enforcement, persistence directness, dispatch reach — so the same program runs as a native app, in a browser, or on bare metal, with the lowering chosen for the coordinate it lands on rather than assumed.

A coding turn, a render frame, a sensor read, a recalled record — none of these is an opaque syscall. Each resolves through an explicit cost-ordered cascade of refine families and stops at the first family that can satisfy it: Lawful (verified primitives; 3.8 µJ measured per refine on Apple silicon) → DeterministicSm → LocalSearch → StateGraph → ConstrainedSearch → TinyRecursive → LlmInLoop (no measured figure yet). Across the reference benchmark's hand-written corpus an intent costs 42.65 µJ, measured on an M3 Ultra, and 87% are answered without a model (7 November 2026). Inference is the last resort, never the entry point; check is deterministic (Schema / ConstraintEval / ProvenanceVerify), never an LLM-as-judge.

The runtime is intentionally ownerless at the protocol level: permissive licensing on the spec text and reference code, a conformance suite so any implementer can verify the invariants without a trust relationship with the authors, and an energy oracle that tags every reading with its honest provenance (⚡AmuAgx measured vs ~Estimator) — never claiming an accuracy the platform cannot deliver. Transaction Science is one steward: it publishes the spec, ships the reference implementation, and operates commercial services around the runtime — not its proprietor.

The doctrine

Capability per joule, not capability per cycle. The durable layer of an operating system is not the scheduler or the window server — both are commoditized. It is the substrate, measured in honest joules per bit of useful work. "Make it correct" and "don't waste energy" are the same optimization: thrash is simultaneously the bug and the energy leak.

Four consequences, normative in the runtime's conformance suite:

1. The single-level store. The in-memory bytes ARE the durable bytes — no serialize/deserialize step. State lives in an mmap'd arena keyed by stable ObjIds; every mutation is wrapped in a per-mutation transaction with an undo log, so a power loss at any instruction boundary either rolls back or commits, never tears. The lineage is Twizzler (USENIX ATC '20) and Corundum (ASPLOS '21), rebuilt lean.

2. The cascade. Every intent dispatches through the cost-ordered refine families above and stops at the cheapest that closes it. LlmInLoop is a real fallback when an endpoint is configured, and otherwise sits in the chain but never satisfies — the floor degrades honestly, it does not fake.

3. The capability ledger. Unforgeable by construction: a Capability<T> can only be produced by the kernel's Ledger::issue. Intersection delegation, constructive revocation via a generation flag, and eight typed capability classes (Storage, NetworkSend, Inference, SensorAcquire, ActuatorIssue, MemoryRecall, DisplayOutput, CodeGen) cover every gated I/O path. The kernel TCB is no_std; the JIT (Cranelift) lives outside the TCB and literally cannot link into it — that is the proof, not the policy.

4. The receipt. Energy is measured, not estimated where hardware allows: AppleSiliconOracle reads ri_energy_nj from proc_pid_rusage (AMU on M-class), RaplOracle on Linux, EstimatorOracle elsewhere — every reading provenance-tagged. Work is pinned across eight non-fungible work classes (W_render, W_infer, W_storage, W_network, W_sensing, W_control, W_string, W_recall); classes are never summed — J/W is per-class. Action Receipts are sealed today as canonical JSON, hashed with BLAKE3 and signed with Ed25519; they are not yet JCR-1, and their joule figure does not yet carry its meter. Sealing every act as a JCR-1 envelope, with the meter's source and boundary inside the signature, is the next step.

Contents

• SPEC.md — the normative specification: the control vector, the single-level store invariants, the refine-family cascade, the capability classes, the work classes, and the receipt schema. (In progress — the canonical reference is the implementation's os-notes/ design stack below.)
• Reference implementation: the joule-os workspace — joule-os-kernel (the no_std TCB: ledger, capability, IR, constraint, check, pipeline, dispatch, substrate, energy, work, persist-arena, the refine families), joule-os-jit (Cranelift, out of TCB), joule-os-shell / -compositor (the surface, no_std + alloc), and the three surfaces joule-os-native (winit + wgpu), joule-os-pwa (wasm + WebGPU), and joule-os-baremetal-kernel (x86_64-unknown-none).
• Design stack (os-notes/): UDA.md (the architecture), LOWERING.md (the implementation spec), THEOREM.md (invariants I1–I20), Q1_W_DEFINITION.md (the eight work classes), SLS_CUTOVER.md (the single-level-store cutover).
• Conformance: joule-os-conformance — dedicated tests for eight of the twenty THEOREM v0.2 invariants (I3, I7, I8, I9, I15, I17, I19, I20), plus lowering_aot_jit.rs asserting AOT ≡ JIT bit-for-bit.

Relationship to the family

Joule OS does not replace the cargo-class standards — it runs them. The cascade is the runtime expression of EOC; the capability ledger is a kernel-local realization of the same object-capability discipline JCP enforces over the wire; the receipts are moving to JCR-1, shared with every sibling. A program written against Joule Code or Smart Byte does not know which surface it will be lowered to — that is the runtime's job, decided at boot against the coordinate it finds itself on.

Status

v0.1 reference. The single-level-store cutover has landed; the capability ledger, the refine-family cascade, the measured energy oracle (Apple Silicon AMU / Linux RAPL / estimator), and the AOT interpreter with the optional Cranelift JIT tier are implemented across the native, PWA, and bare-metal surfaces. The conformance suite tests eight of the twenty THEOREM invariants and the AOT ≡ JIT equivalence; the runtime's full test suite passed on a clean build host on 7 November 2026. Not certified for production deployment; the bare-metal surface is a development target, not a shipping OS.

Licence

Apache-2.0 for reference code (see LICENSE). Specification text, when published, is CC-BY-4.0.

• Site: jos.transaction.science