{{box cssClass="floatinginfobox" title="**Quick Facts**"}} * **Kernel**: LithosAnanake v2.0.0 * **VM**: StarForth v3.1.0 * **Architectures**: amd64 · aarch64 · riscv64 * **Status**: M7.1 In Progress * **License**: [[Starship License 1.0>>https://strshipos.org]] * **Patent**: USPTO Provisional (Dec 2025) {{/box}} = StarshipOS = StarshipOS is a **UEFI-bootable bare-metal FORTH microkernel** that boots directly from firmware with no libc and no operating system beneath it — just hardware, a kernel, and a FORTH runtime. Its tagline is //stone and necessity.// The system is composed of two tightly coupled components: * **LithosAnanake** — the kernel (Greek: //Lithos// = stone, //Ananake// = necessity) * **StarForth** — a Compudynamics FORTH-79 VM that is the sole userspace runtime ---- == Architecture == === The Kernel: LithosAnanake === LithosAnanake is a minimal UEFI-bootable microkernel. It handles: * Physical Memory Manager (PMM) * Virtual Memory Manager (VMM) * Interrupt Descriptor Table (IDT) and APIC * Heap allocator * Framebuffer with VT100 console * VirtIO block device (storage via virtio-blk) * Capsule birth, load, and run lifecycle The kernel targets **three architectures** simultaneously: **amd64**, **aarch64**, and **riscv64**. The only valid acceptance test is booting all three in QEMU and capturing serial logs. === StarForth: The Compudynamics VM === StarForth is not a conventional FORTH interpreter. It is a **self-adaptive runtime** governed by a system of Compudynamics feedback loops that continuously tune execution behavior at runtime — no offline profiling, no hand-tuning. ==== The 7 Feedback Loops + L8 Jacquard ==== |=Loop|=Name|=Mechanism |1|Execution Heat|Frequency counter per word |2|Rolling Window|Circular buffer of execution history |3|Linear Decay|Quiescent words lose heat over time |4|Pipelining|Word-to-word transition prediction |5|Window Width Inference|Levene's test + binary chop |6|Decay Slope Inference|Exponential regression |7|Adaptive Heartrate|Background tick coordinator |L8|**Jacquard Mode Selector**|128-state 7-bit gate routing loop signals into fleet-wide tuning The Jacquard layer (L8) is the keystone: it reads the outputs of all 7 loops and selects the VM's operating mode, feeding a per-VM heat channel into fleet-wide tuning across the Tripod. ---- == The Tripod Fleet == StarForth runs as a fleet of three independent VMs called the **Tripod**: |=VM|=Role |**Hera**|Fleet coordinator and policy anchor |**Artemis**|Workload execution VM |**Hestia**|Stability and quorum VM Each VM in the Tripod is born, run, and re-born independently. All three are verified on all three architectures. {{info}} **Note on Hermes**: Earlier documentation refers to a "Tripod + Hermes" configuration. As of M7.1 Phase 4 (2026-09-22), Hermes was moved into the kernel itself as //kernel-Hermes// (`kernel_hermes.c`). The Tripod is Hera, Artemis, and Hestia only. Any document describing Hermes as a Tripod VM is superseded. {{/info}} ---- == Capsules == The primary unit of organization in StarForth is the **content-addressed immutable capsule**, identified by XXHash64. Capsules are born, loaded, and run through a formal protocol — they cannot be mutated in place. Block namespace allocation: |=Block Range|=Purpose |2048–2099|init.4th only |2100–2199|doe.4th only |3000–3999|Workload capsules |4000–4015|ACL.4th |4016–4018|zuse.4th |4019+|User-defined Each block is strictly **64 characters × 16 lines = 1024 bytes**. This constraint is non-negotiable. ---- == Word-Level ACL Security == Every dictionary word carries a 4-field ACL structure: * **acl_ttl** — time-to-live for the permission * **acl_allow** — permission bitmap * **acl_mode** — operating mode * **acl_pinned** — kernel-pinned flag (set in C after capsule load for kernel-only words) Plus two VM-level flags: `emergency_console` and `zuse_session`. ACL policy is defined in **ACL.4th**, not in C. Measured overhead: **+0.0603%**, CV = 0.000%. The **Mama capsule** dictionary ships ~530 words covering the full FORTH-79 standard plus StarForth extensions. ---- == Formal Verification == The project includes **52 Isabelle/HOL theory files** (47 StarForth_* + 5 ACL_*). The goal is not a green build — it is **boundary identification**: rigorously characterising the limits of correctness guarantees. See `proof/COVERAGE.md` for scope. ---- == Milestone Status == |=Milestone|=Description|=Status |M0|UEFI boot|✅ Complete |M1|Physical Memory Manager|✅ Complete |M2|Virtual Memory Manager|✅ Complete |M3|IDT + Interrupts|✅ Complete |M4|APIC|✅ Complete |M5|Heap allocator|✅ Complete |M6|Framebuffer + VT100|✅ Complete |M7|StarForth VM integration + parity validation|✅ Complete |**M7.1**|Capsule birth protocol, Mama vocabulary, Tripod fleet, word-level ACL Phases 1–7|🔄 **In Progress** |M7.1 Phase 8|Ed25519 PKI / thumbdrive challenge-response|📋 Planned |M8|TBD|📋 Planned |M9|VirtIO block storage|✅ Complete ---- == Build == {{code language="bash"}} # Kernel — all three architectures make -f kernel/Makefile ARCH=amd64 clean qemu make -f kernel/Makefile ARCH=aarch64 clean qemu make -f kernel/Makefile ARCH=riscv64 clean qemu # Interactive Kconfig make -f kernel/Makefile ARCH=amd64 menuconfig {{/code}} {{warning}} The hosted `make` build is a **sanity check only**. It is never used to validate kernel changes. All acceptance testing requires booting all three architectures in QEMU and capturing serial output. {{/warning}} ---- == License == StarshipOS is released under the **Starship License 1.0 (SL-1.0)**: * ✅ Free for personal, research, and educational use * ❌ Commercial use requires a separate agreement * ⚠️ Attribution to **R.A. James ("Captain Bob")** is mandatory in all distributions The Compudynamics self-adaptive runtime system is **patent pending** (USPTO provisional, December 2025). The license does not grant patent rights. Licensing enquiries: [[rajames440@gmail.com>>mailto:rajames440@gmail.com]]