Robert Allan James
936d046ca6
The Zynq FPGA is not a fourth platform to port to — it is the pivot that
forces the project into three distinct products, each with its own host,
delivery, and proof character (decided 2026-08-29):
1. Hosted StarForth - the existing hosted/interpreted StarForth runtime
(3-arch acceptance-tested), delivered as a portable embedded runtime.
2. A full StarshipOS - the standalone OS built on LithosAnanke
(LithosAnanke -> StarshipOS), a self-booting OS on general silicon
(SER5/RasPi/Milk-V line).
3. Hardware steady-state machinery with sealed executions, HOL-proven -
the FPGA-native product: hardware-enforced sealed executions and
steady-state machinery machine-checked in a proof assistant (HOL);
delivery is the bitstream + HOL proof artifacts, not just an OS port.
The coupling is the point: product 3 is born on the FPGA, and its existence
is what cleanly separates 1 from 2 from 3. Product 1 ships hosted on an OS,
product 2 as an OS on general silicon, product 3 as proven hardware. Per-
product gates and the even-major line carrying the three as separate tracks
are scoped at v2.5.0 close / during the coloring-in phase. Complements, and
does not retract, the existing hardware bare-metal release policy.
Authoritative form in ROADMAP.md; FABRIC-3.md tracks the same horizon.
LithosAnanke — StarForth Kernel Branch
Branch: lithosananke
Status: M7 Complete (VM Parity Validation)
Parent: master (hosted StarForth)
What is LithosAnanke?
LithosAnanke is the kernel branch of StarForth — a UEFI-bootable microkernel with the StarForth VM as its native execution engine.
Etymology: Lithos (stone/foundation) + Ananke (necessity/inevitability)
The name reflects the project's nature: a necessary foundation for StarshipOS.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ UEFI Firmware │
│ • ExitBootServices → handoff to kernel │
└─────────────────────┬───────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ LithosAnanke Boot (M0) │
│ • UEFI loader collects BootInfo │
│ • Memory map, ACPI tables, framebuffer │
└─────────────────────┬───────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ LithosAnanke HAL (M1-M6) │
│ • PMM: Physical Memory Manager (bitmap) │
│ • VMM: Virtual Memory Manager (4-level paging) │
│ • IDT: Interrupt Descriptor Table │
│ • APIC: Timer + IRQ routing │
│ • Heap: kmalloc/kfree │
│ • Console: Serial UART │
└─────────────────────┬───────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ StarForth VM (M7+) │
│ • 295 FORTH-79 words │
│ • Parity validation (hash=0x684bbf2fa1d96d55) │
│ • Physics-driven adaptive runtime │
│ • Init capsule system (M7.1) │
└─────────────────────────────────────────────────────────────┘
Current Milestones
| Milestone | Description | Status |
|---|---|---|
| M0 | UEFI Boot + Serial Output | Complete |
| M1 | Physical Memory Manager | Complete |
| M2 | Virtual Memory Manager | Complete |
| M3 | IDT + Interrupts | Complete |
| M4 | APIC Timer | Complete |
| M5 | Timer Calibration | Complete |
| M6 | Kernel Heap | Complete |
| M7 | VM Parity Validation | Complete |
| M7.1 | Init Capsule Architecture | Design Complete |
| M8 | REPL + Interactive Forth | Planned |
| M9 | Block Storage | Planned |
Build & Run
# Build kernel with VM integration
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1
# Run in QEMU
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
Output artifacts:
build/amd64/kernel/starkernel_loader.efi— UEFI loaderbuild/amd64/kernel/starkernel_kernel.elf— Kernel binary
Documentation
Core Design
| Document | Description |
|---|---|
| M7.1.md | Init Capsule Architecture |
| ROADMAP.md | Milestone roadmap |
| amd64-isr-fix/README.md | APIC timer ISR fix + kernel 3-arch acceptance test |
| hosted-acceptance-test/README.md | Hosted VM 3-arch acceptance test (amd64 native, aarch64/riscv64 under QEMU user-mode) |
HAL (Hardware Abstraction Layer)
| Document | Description |
|---|---|
| hal/overview.md | HAL architecture and principles |
| hal/interfaces.md | HAL interface specifications |
| hal/lithosananke-integration.md | Kernel-specific HAL implementation |
| hal/platform-implementations.md | Platform implementation guide |
| hal/migration-plan.md | Migration from hosted to kernel |
Key Concepts
One Truth Per VM
Every VM has exactly one birth capsule — its identity and provenance.
PARITY:BIRTH vm_id=42 capsule_id=0xA13F mode=p capsule_hash=0x... dict_hash=0x...
DOMAIN vs PERSONALITY
DOMAIN is a construction concept that exists only in Mama FORTH. It's how Mama classifies, composes, and selects capsules. DOMAIN is never visible to baby VMs.
PERSONALITY is the result of executing a production (p) INIT capsule. It's what the baby VM is — its vocabulary, invariants, capabilities. PERSONALITY is immutable and defines the VM's entire worldview.
Production (p) vs Experiment (e)
- (p) capsules are truth-bearing — they can birth VMs
- (e) capsules are Mama-only workloads — experiments that never touch babies
A baby VM never sees, executes, or knows about (e) capsules.
Content-Addressed Capsules
Capsules are identified by content hash, not names. Names lie. Hashes don't.
Mama FORTH
The root VM that holds all truths, manages child VMs, and enforces the birth protocol. Mama:
- Maintains the capsule directory
- Selects (p) capsules for birth
- Executes (e) capsules for experimentation
- Logs all births and runs for provenance
Directory Structure
src/starkernel/
├── boot/ # UEFI loader, ELF loader
├── hal/ # Console, host services
├── memory/ # PMM, VMM, kmalloc
├── arch/amd64/ # x86_64 specific (APIC, IDT, timer)
├── vm/ # VM integration
│ ├── arena.c # VM memory arena
│ ├── parity.c # Parity validation
│ ├── bootstrap/ # sk_vm_bootstrap
│ └── host/ # Host services shim
└── kernel_main.c # Entry point
Contributing
The lithosananke branch is experimental. Changes should:
- Maintain parity validation (M7 baseline)
- Pass QEMU boot test
- Not break hosted StarForth (master branch)
References
- StarForth README — Main project
- FORTH-79 Standard
- OSDev Wiki
- UEFI Specification