63e2579622
Some checks failed
repository checks / lockfiles, advisories, tests in CI, workflow hygiene, spec and section references, public text (push) Has been cancelled
The repository's no-vanity-metrics check failed on line 40 for a raw test count
("1,984 tests across the runtime"), and every open pull request inherited that
red. The line now says the runtime's full test suite passed on a clean build host
on 7 November 2026; the date and the claim stay, the number goes.
Checked: scripts/check-no-vanity-metrics.sh is clean across all Markdown files.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
46 lines
7.3 KiB
Markdown
46 lines
7.3 KiB
Markdown
# 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](../smart-byte/) carries value, [EOC](../eoc/) carries compute, [Joule Code](../joule-code/) carries coding work, and [Map](../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 `ObjId`s; 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`](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`](https://github.com/transaction-science) 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](../eoc/); the capability ledger is a kernel-local realization of the same object-capability discipline [JCP](../jcp/) enforces over the wire; the receipts are moving to [JCR-1](../joule-code/), 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`](LICENSE)). Specification text, when published, is CC-BY-4.0.
|
||
|
||
- **Site:** [jos.transaction.science](https://jos.transaction.science)
|