XWiki - Main - 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.//

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

----

== Architecture ==

=== 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.

----

== 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

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.

----

== 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.

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

|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 ==

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.

----

== 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.

----

== 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

----

== Build ==

# 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

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.

----

== License ==

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]]

author	version	line-number	content
		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>>http://strshipos.org]] =
		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]]

Wiki source code of StarshipOS