1656af3a8a
New joule-os/ entry (README + Apache-2.0 LICENSE) and root README wiring: the
runtime the cargo-class standards lower onto. Single-level store, energy-tiered
refine cascade, capability ledger, measured energy oracle; JCR-1 receipts shared
with the family. Site: jos.transaction.science.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
(cherry picked from commit b885f1d789)
46 lines
6.7 KiB
Markdown
46 lines
6.7 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, ~1 µJ) → `DeterministicSm` → `LocalSearch` → `StateGraph` → `ConstrainedSearch` → `TinyRecursive` → `LlmInLoop` (~5 mJ). 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. Receipts seal as **JCR-1** envelopes, byte-compatible with the rest of the family's verifiers.
|
||
|
||
## 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` — the THEOREM v0.2 invariants I1–I20 enforced as tests, 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 [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 enforces the THEOREM I1–I20 invariants and the AOT ≡ JIT equivalence. 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)
|