Skip to Content

Wiki source code of StarshipOS

Version 4.1 by XWikiGuest on 2026/10/07 18:28
Show last authors
1 {{box cssClass="floatinginfobox" title="**Quick Facts**"}}
2 * **Kernel**: LithosAnanake v2.0.0
3 * **VM**: StarForth v3.1.0
4 * **Architectures**: amd64 · aarch64 · riscv64
5 * **Status**: M7.1 In Progress
6 * **License**: [[Starship License 1.0>>https://strshipos.org]]
7 * **Patent**: USPTO Provisional (Dec 2025)
8 {{/box}}
9
10 = StarshipOS =
11
12 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.//
13
14 The system is composed of two tightly coupled components:
15
16 * **LithosAnanake** — the kernel (Greek: //Lithos// = stone, //Ananake// = necessity)
17 * **StarForth** — a Compudynamics FORTH-79 VM that is the sole userspace runtime
18
19 ----
20
21 == Architecture ==
22
23 === The Kernel: LithosAnanake ===
24
25 LithosAnanake is a minimal UEFI-bootable microkernel. It handles:
26
27 * Physical Memory Manager (PMM)
28 * Virtual Memory Manager (VMM)
29 * Interrupt Descriptor Table (IDT) and APIC
30 * Heap allocator
31 * Framebuffer with VT100 console
32 * VirtIO block device (storage via virtio-blk)
33 * Capsule birth, load, and run lifecycle
34
35 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.
36
37 === StarForth: The Compudynamics VM ===
38
39 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.
40
41 ==== The 7 Feedback Loops + L8 Jacquard ====
42
43 |=Loop|=Name|=Mechanism
44 |1|Execution Heat|Frequency counter per word
45 |2|Rolling Window|Circular buffer of execution history
46 |3|Linear Decay|Quiescent words lose heat over time
47 |4|Pipelining|Word-to-word transition prediction
48 |5|Window Width Inference|Levene's test + binary chop
49 |6|Decay Slope Inference|Exponential regression
50 |7|Adaptive Heartrate|Background tick coordinator
51 |L8|**Jacquard Mode Selector**|128-state 7-bit gate routing loop signals into fleet-wide tuning
52
53 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.
54
55 ----
56
57 == The Tripod Fleet ==
58
59 StarForth runs as a fleet of three independent VMs called the **Tripod**:
60
61 |=VM|=Role
62 |**Hera**|Fleet coordinator and policy anchor
63 |**Artemis**|Workload execution VM
64 |**Hestia**|Stability and quorum VM
65
66 Each VM in the Tripod is born, run, and re-born independently. All three are verified on all three architectures.
67
68 {{info}}
69 **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.
70 {{/info}}
71
72 ----
73
74 == Capsules ==
75
76 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.
77
78 Block namespace allocation:
79
80 |=Block Range|=Purpose
81 |2048–2099|init.4th only
82 |2100–2199|doe.4th only
83 |3000–3999|Workload capsules
84 |4000–4015|ACL.4th
85 |4016–4018|zuse.4th
86 |4019+|User-defined
87
88 Each block is strictly **64 characters × 16 lines = 1024 bytes**. This constraint is non-negotiable.
89
90 ----
91
92 == Word-Level ACL Security ==
93
94 Every dictionary word carries a 4-field ACL structure:
95
96 * **acl_ttl** — time-to-live for the permission
97 * **acl_allow** — permission bitmap
98 * **acl_mode** — operating mode
99 * **acl_pinned** — kernel-pinned flag (set in C after capsule load for kernel-only words)
100
101 Plus two VM-level flags: `emergency_console` and `zuse_session`.
102
103 ACL policy is defined in **ACL.4th**, not in C. Measured overhead: **+0.0603%**, CV = 0.000%.
104
105 The **Mama capsule** dictionary ships ~530 words covering the full FORTH-79 standard plus StarForth extensions.
106
107 ----
108
109 == Formal Verification ==
110
111 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.
112
113 ----
114
115 == Milestone Status ==
116
117 |=Milestone|=Description|=Status
118 |M0|UEFI boot|✅ Complete
119 |M1|Physical Memory Manager|✅ Complete
120 |M2|Virtual Memory Manager|✅ Complete
121 |M3|IDT + Interrupts|✅ Complete
122 |M4|APIC|✅ Complete
123 |M5|Heap allocator|✅ Complete
124 |M6|Framebuffer + VT100|✅ Complete
125 |M7|StarForth VM integration + parity validation|✅ Complete
126 |**M7.1**|Capsule birth protocol, Mama vocabulary, Tripod fleet, word-level ACL Phases 1–7|🔄 **In Progress**
127 |M7.1 Phase 8|Ed25519 PKI / thumbdrive challenge-response|📋 Planned
128 |M8|TBD|📋 Planned
129 |M9|VirtIO block storage|✅ Complete
130
131 ----
132
133 == Build ==
134
135 {{code language="bash"}}
136 # Kernel — all three architectures
137 make -f kernel/Makefile ARCH=amd64 clean qemu
138 make -f kernel/Makefile ARCH=aarch64 clean qemu
139 make -f kernel/Makefile ARCH=riscv64 clean qemu
140
141 # Interactive Kconfig
142 make -f kernel/Makefile ARCH=amd64 menuconfig
143 {{/code}}
144
145 {{warning}}
146 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.
147 {{/warning}}
148
149 ----
150
151 == License ==
152
153 StarshipOS is released under the **Starship License 1.0 (SL-1.0)**:
154
155 * ✅ Free for personal, research, and educational use
156 * ❌ Commercial use requires a separate agreement
157 * ⚠️ Attribution to **R.A. James ("Captain Bob")** is mandatory in all distributions
158
159 The Compudynamics self-adaptive runtime system is **patent pending** (USPTO provisional, December 2025). The license does not grant patent rights.
160
161 Licensing enquiries: [[rajames440@gmail.com>>mailto:rajames440@gmail.com]]